Common Functions

The HCL supports various built-in functions you can call by function name for processing strings, calculating values, encrypting values, and converting types. The syntax is as follows:

<Function name>(<Argument 1>, <Argument 2>...)

This section summarizes common functions in HCL and uses examples to describe their usage. For details about the complete list of supported functions, see Terraform Functions.

String Functions

**Table 1** String functions
Name	Description	Example Value	Output
format	Produces a string by formatting a number of other values according to a specification string.	format("Hello, %s!", "cloud")	Hello, cloud!
lower	Converts all letters in the given string to lowercase.	lower("HELLO")	hello
upper	Converts all letters in the given string to uppercase.	upper("hello")	HELLO
join	Produces a string by concatenating together all elements of a given list of strings with the given delimiter.	join(", ", ["One", "Two", "Three"])	One, Two, Three
split	Produces a list by dividing a given string at all occurrences of a given separator.	split(", ", "One, Two, Three")	["One", "Two", "Three"]
substr	Extracts a substring from a given string by offset and length.	substr("hello world!", 1, 4)	ello
replace	Searches a given string for another given substring, and replaces each occurrence with a given replacement string.	replace("hello, cloud!", "h", "H")	Hello, cloud!

Numeric Functions

**Table 2** Numeric functions
Name	Description	Example Value	Output
abs	Returns the absolute value of the given number.	abs(-12.4)	12.4
max	Takes one or more numbers and returns the greatest number from the set.	max(12, 54, 6) max([12, 54, 6]...)	54 54
min	Takes one or more numbers and returns the smallest number from the set.	min(12, 54, 6) min([12, 54, 6]...)	6 6
log	Returns the logarithm of a given number in a given base.	log(16, 2)	4
power	Calculates an exponent, by raising its first argument to the power of the second argument.	power(3, 2)	9

Collection Functions

**Table 3** Collection functions
Name	Description	Example Value	Output
element	Retrieves a single element from a list by an index.	element(["One", "Two", "Three"], 1)	Two
index	Finds the element index for a given value in a list. If the given value is not present in the list, an error is reported.	index(["a", "b", "c"], "b")	1
lookup	Retrieves the value of a single element from a map, given its key. If the given key does not exist, the given default value is returned instead.	lookup({IT="A", CT="B"}, "IT", "G") lookup({IT="A", CT="B"}, "IE", "G")	A G
flatten	Replaces any elements that are lists with a flattened sequence of the list contents.	flatten([["a", "b"], [], ["c"]])	["a", "b", "c"]
keys	Returns a list containing the keys from a map.	keys({a=1, b=2, c=3})	["a", "b", "c"]
length	Determines the length of a given list, map, or string.	length(["One", "Two", "Three"]) length({IT="A", CT="B"}) length("Hello, cloud!")	3 2 13

Type Conversion Functions

**Table 4** Type conversion functions
Name	Description	Example Value	Output
toset	Converts a list value to a set value.	toset(["One", "Two", "One"])	["One", "Two"]
tolist	Converts a set value to a list value.	toset(["One", "Two", "Three"])	["One", "Two", "Three"]
tonumber	Converts a string value to a number value.	tonumber("33")	33
tostring	Converts a number value to a string value.	tostring(33)	"33"

Encoding Functions

**Table 5** Encoding functions
Name	Description	Example Value	Output
base64encode	Encodes a UTF-8 string using Base64.	base64encode("Hello, cloud!")	SGVsbG8sIGNsb3VkIQ==
base64decode	Decodes a Base64-encoded string to its original UTF-8 string. (If the bytes after Base64 decoding are not valid UTF-8, an error is reported.)	base64decode("SGVsbG8sIGNsb3VkIQ==")	Hello, cloud!
base64gzip	Compresses a UTF-8 string with gzip and then encodes the result using Base64.	base64gzip("Hello, cloud!")	H4sIAAAAAAAA//JIzcnJ11FIzskvTVEEAAAA//8BAAD//wbrhYUNAAAA

Hash and Crypto Functions

**Table 6** Hash and crypto functions
Name	Description	Example Value	Output
sha256	Computes the SHA256 hash (hexadecimal) of a given string.	sha256("Hello, cloud!")	0ad167d1e3ac8e9f4e4f7ba83e92d0e3838177e959858631c770caaed8cc5e3a
sha512	Computes the SHA512 hash (hexadecimal) of a given string.	sha512("Hello, cloud!")	6eb6ed9fc4edffaf90e742e7697f6cc7d8548e98aa4d5aa74982e5cdf78359e84a3ae9f226313b2dec765bf1ea4c83922dbfe4a61636d585da44ffbd7e900f56
base64sha256	Computes the SHA256 hash of a given string and encodes it using Base64.	base64sha256("Hello, cloud!")	CtFn0eOsjp9OT3uoPpLQ44OBd+lZhYYxx3DKrtjMXjo=
base64sha512	Computes the SHA512 hash of a given string and encodes it using Base64.	base64sha512("Hello, cloud!")	brbtn8Tt/6+Q50LnaX9sx9hUjpiqTVqnSYLlzfeDWehKOunyJjE7Lex2W/HqTIOSLb/kphY21YXaRP+9fpAPVg==
md5	Computes the MD5 hash of a given string.	md5("hello world")	5eb63bbbe01eeed093cb22bb8f5acdc3

The output of base64sha512("Hello, cloud!") is not equal to that of base64encode(sha512("Hello, cloud!")), because the hexadecimal output of sha512 is Unicode-encoded in Terraform, not UTF-8.

Filesystem Functions

**Table 7** Filesystem functions
Name	Description	Example Value	Output
abspath	Converts a string containing a filesystem path to an absolute path.	abspath("./hello.txt")	/home/demo/test/terraform/hello.txt
dirname	Removes the last portion from a string containing a filesystem path.	dirname("foo/bar/baz.txt")	foo/bar
basename	Removes all except the last portion from a string containing a filesystem path.	basename("foo/bar/baz.txt")	baz.txt
file	Reads the contents of a file at the given path and returns them as a string.	file("./hello.txt")	Hello, cloud!
filebase64	Reads the contents of a file at the given path and returns them as a Base64-encoded string.	filebase64("./hello.txt")	SGVsbG8sIGNsb3VkIQ==