Collection Functions

Collection functions provide operations for manipulating lists, maps, and sets in HCL expressions.

Function Reference

chunklist

Splits a list into fixed-size chunks.

chunklist(list, chunk_size)

Parameters:

• list - List to split
• chunk_size - Size of each chunk

Returns: List of lists

Example:

chunklist(["a", "b", "c", "d", "e"], 2)
# Returns: [["a", "b"], ["c", "d"], ["e"]]

chunklist([1, 2, 3, 4, 5, 6], 3)
# Returns: [[1, 2, 3], [4, 5, 6]]

coalescelist

Returns the first non-empty list from the arguments.

coalescelist(lists...)

Parameters:

• lists... - One or more lists

Returns: First non-empty list

Example:

coalescelist([], ["a", "b"], ["c", "d"])      # Returns: ["a", "b"]
coalescelist(var.custom_list, ["default"])     # Returns: custom_list or ["default"]
coalescelist([], [], ["fallback"])             # Returns: ["fallback"]

compact

Removes null and empty string elements from a list.

compact(list)

Parameters:

• list - List of strings

Returns: List with null and empty strings removed

Example:

compact(["a", "", "b", null, "c"])     # Returns: ["a", "b", "c"]
compact(["", "", ""])                   # Returns: []
compact(["hello", "world"])             # Returns: ["hello", "world"]

concat

Combines multiple lists into a single list.

concat(lists...)

Parameters:

• lists... - Lists to combine

Returns: Combined list

Example:

concat(["a", "b"], ["c", "d"])         # Returns: ["a", "b", "c", "d"]
concat([1, 2], [3], [4, 5])            # Returns: [1, 2, 3, 4, 5]
concat([], ["a"], [])                  # Returns: ["a"]

contains

Checks if a collection contains a specific value.

contains(list, value)

Parameters:

• list - List, tuple, or set to search
• value - Value to find

Returns: Boolean (true if value is found)

Example:

contains(["a", "b", "c"], "b")         # Returns: true
contains([1, 2, 3], 4)                 # Returns: false
contains(["web", "api"], "web")        # Returns: true

distinct

Removes duplicate elements from a list.

distinct(list)

Parameters:

• list - List with potential duplicates

Returns: List with unique elements

Example:

distinct([1, 2, 2, 3, 1, 4])           # Returns: [1, 2, 3, 4]
distinct(["a", "b", "a", "c"])         # Returns: ["a", "b", "c"]
distinct([])                           # Returns: []

element

Retrieves an element at a specific index.

element(list, index)

Parameters:

• list - List to access
• index - Index position (wraps around if out of bounds)

Returns: Element at the index

Example:

element(["a", "b", "c"], 1)            # Returns: "b"
element(["a", "b", "c"], 3)            # Returns: "a" (wraps to index 0)
element(["a", "b", "c"], -1)           # Returns: "c" (negative wraps)

flatten

Flattens nested lists into a single list.

flatten(list)

Parameters:

• list - List potentially containing nested lists

Returns: Flattened list

Example:

flatten([["a", "b"], ["c"]])           # Returns: ["a", "b", "c"]
flatten([[1, 2], [3, [4, 5]]])         # Returns: [1, 2, 3, 4, 5]
flatten(["a", ["b", ["c"]]])           # Returns: ["a", "b", "c"]

keys

Returns the keys from a map.

keys(map)

Parameters:

• map - Map to extract keys from

Returns: List of keys (sorted)

Example:

keys({a = 1, b = 2, c = 3})            # Returns: ["a", "b", "c"]
keys({web = 80, api = 8080})           # Returns: ["api", "web"]
keys({})                               # Returns: []

len

Returns the number of elements in a collection.

len(value)

Parameters:

• value - List, map, string, or tuple

Returns: Number of elements

Example:

len([1, 2, 3])                      # Returns: 3
len({a = 1, b = 2})                 # Returns: 2
len("hello")                        # Returns: 5
len([])                             # Returns: 0

merge

Combines multiple maps into a single map.

merge(maps...)

Parameters:

• maps... - Maps to merge (later values override earlier)

Returns: Merged map

Example:

merge({a = 1}, {b = 2})                # Returns: {a = 1, b = 2}
merge({a = 1}, {a = 2})                # Returns: {a = 2}
merge({a = 1}, {b = 2}, {c = 3})      # Returns: {a = 1, b = 2, c = 3}

range

Generates a sequence of numbers.

range(limit)
range(start, limit)
range(start, limit, step)

Parameters:

• start - Starting value (default: 0)
• limit - Upper limit (exclusive)
• step - Increment (default: 1)

Returns: List of numbers

Example:

range(3)                               # Returns: [0, 1, 2]
range(1, 4)                            # Returns: [1, 2, 3]
range(0, 10, 2)                        # Returns: [0, 2, 4, 6, 8]
range(5, 0, -1)                        # Returns: [5, 4, 3, 2, 1]

reverse

Reverses the order of elements.

reverse(list)

Parameters:

• list - List or tuple to reverse

Returns: Reversed sequence

Example:

reverse([1, 2, 3])                     # Returns: [3, 2, 1]
reverse(["a", "b", "c"])               # Returns: ["c", "b", "a"]
reverse([])                            # Returns: []

setintersection

Finds common elements across sets.

setintersection(sets...)

Parameters:

• sets... - Sets to intersect

Returns: Set of common elements

Example:

setintersection([1, 2, 3], [2, 3, 4])  # Returns: [2, 3]
setintersection(["a", "b"], ["b", "c"], ["b", "d"])  # Returns: ["b"]
setintersection([1, 2], [3, 4])        # Returns: []

setproduct

Calculates the Cartesian product of sets.

setproduct(sets...)

Parameters:

• sets... - Sets to combine

Returns: List of all combinations

Example:

setproduct(["a", "b"], [1, 2])
# Returns: [["a", 1], ["a", 2], ["b", 1], ["b", 2]]

setproduct(["dev", "prod"], ["us", "eu"])
# Returns: [["dev", "us"], ["dev", "eu"], ["prod", "us"], ["prod", "eu"]]

setsubtract

Removes elements of one set from another.

setsubtract(set1, set2)

Parameters:

• set1 - Set to subtract from
• set2 - Set of elements to remove

Returns: Set with elements removed

Example:

setsubtract([1, 2, 3], [2, 3])         # Returns: [1]
setsubtract(["a", "b", "c"], ["d"])    # Returns: ["a", "b", "c"]
setsubtract(["a", "b"], ["a", "b"])    # Returns: []

setunion

Combines multiple sets removing duplicates.

setunion(sets...)

Parameters:

• sets... - Sets to combine

Returns: Combined set without duplicates

Example:

setunion([1, 2], [2, 3])               # Returns: [1, 2, 3]
setunion(["a"], ["b"], ["c"])          # Returns: ["a", "b", "c"]
setunion([1, 2], [2, 3], [3, 4])       # Returns: [1, 2, 3, 4]

slice

Extracts a portion of a list.

slice(list, start, end)

Parameters:

• list - List to slice
• start - Starting index (inclusive)
• end - Ending index (exclusive)

Returns: Extracted portion

Example:

slice(["a", "b", "c", "d"], 1, 3)      # Returns: ["b", "c"]
slice([1, 2, 3, 4, 5], 0, 2)           # Returns: [1, 2]
slice(["a", "b", "c"], 2, 10)          # Returns: ["c"]

sort

Sorts a list of strings lexicographically.

sort(list)

Parameters:

• list - List of strings to sort

Returns: Sorted list

Example:

sort(["banana", "apple", "cherry"])    # Returns: ["apple", "banana", "cherry"]
sort(["3", "1", "2"])                  # Returns: ["1", "2", "3"]
sort(["Z", "a", "B"])                  # Returns: ["B", "Z", "a"]

values

Returns the values from a map.

values(map)

Parameters:

• map - Map to extract values from

Returns: List of values

Example:

values({a = 1, b = 2, c = 3})          # Returns: [1, 2, 3]
values({web = "nginx", db = "postgres"}) # Returns: ["nginx", "postgres"]
values({})                             # Returns: []

zipmap

Creates a map from parallel lists of keys and values.

zipmap(keys, values)

Parameters:

• keys - List of keys
• values - List of values

Returns: Map combining keys and values

Example:

zipmap(["a", "b", "c"], [1, 2, 3])
# Returns: {a = 1, b = 2, c = 3}

zipmap(["web", "api"], ["80", "8080"])
# Returns: {web = "80", api = "8080"}

Common Use Cases

Dynamic Resource Creation

variable "environments" {
  default = ["dev", "staging", "prod"]
}

resource "container" "app" {
  for_each = distinct(var.environments)

  image {
    name = "app:${each.value}"
  }
}

Configuration Merging

locals {
  default_config = {
    timeout = 30
    retries = 3
  }

  final_config = merge(
    local.default_config,
    var.custom_config
  )
}

List Processing

locals {
  # Remove empty values and duplicates
  clean_domains = distinct(compact(var.domains))

  # Create pairs of services and ports
  service_ports = zipmap(
    var.service_names,
    var.service_ports
  )
}

Set Operations

locals {
  # Find common regions
  available_regions = setintersection(
    var.requested_regions,
    data.cloud.available_regions
  )

  # Remove blocked IPs
  allowed_ips = setsubtract(
    var.all_ips,
    var.blocked_ips
  )
}

Best Practices

1. Use Type-Appropriate Functions: Choose functions that match your data structure

   # For unique values, use distinct
   locals {
     unique_tags = distinct(var.tags)
   }

2. Handle Empty Collections: Consider edge cases with empty inputs

   locals {
     safe_list = coalescelist(var.custom_list, ["default"])
     first_item = len(var.items) > 0 ? element(var.items, 0) : "none"
   }

3. Maintain Readability: Break complex operations into steps

   locals {
     # Step 1: Clean the data
     cleaned = compact(var.raw_data)
     # Step 2: Remove duplicates
     unique = distinct(local.cleaned)
     # Step 3: Sort the result
     final = sort(local.unique)
   }

4. Consider Performance: Use efficient operations for large collections

   # Use contains() instead of looping
   locals {
     has_prod = contains(var.environments, "production")
   }