Map

Provides operations to manipulate key/value pairs stored as map. It requires CMake 4.0.1 or newer.

Synopsis

Reading
  map(SIZE <map-var> <output-var>)
  map(GET <map-var> <key> <output-var>)
  map(KEYS <map-var> <output-list-var>)
  map(VALUES <map-var> <output-list-var>)

Search
  map(FIND <map-var> <key> <output-var>)
  map(SEARCH <map-var> <value> <output-list-var>)
  map(HAS_KEY <map-var> <key> <output-var>)
  map(HAS_VALUE <map-var> <value> <output-var>)

Modification
  map(SET <map-var> <key> <value>)
  map(ADD <map-var> <key> <value>)
  map(REMOVE <map-var> <key>)

Introduction

A map is represented as a list() of strings, where each string must contain a single colon (:) separating the key from its value (e.g. <key>:<value>). Malformed entries, such as those with no colon, empty key, or multiple colons, are ignored in most operations. A warning is emitted when malformed entries are encountered.

Reading

map(SIZE <map-var> <output-var>)

Store in output-var the number of valid key/value pairs in the map map-var. Entries with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(SIZE input_map size)
# size is 4, the two last entries are invalid and ignored, but "four:4:4"
# is valid

map(GET <map-var> <key> <output-var>)

Store in output-var the value associated with key in map-var. An error is raised if the key is not found or malformed in the list.

Compared to map(FIND), this command is stricter: it raises an error instead of setting <key>-NOTFOUND.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(GET input_map "four" value)
# value is:
#   "4:4"
map(GET input_map "invalid" value)
# Uncaught exception: Cannot find the key 'invalid'!

map(KEYS <map-var> <output-list-var>)

Store in output-list-var the list of keys found in map-var. Entries with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(KEYS input_map map_keys)
# map_keys is:
#   one;two;three;four

map(VALUES <map-var> <output-list-var>)

Store in output-list-var the list of values from map-var. Entries with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(VALUES input_map map_values)
# map_values is:
#   1;2;;4:4

Search

map(FIND <map-var> <key> <output-var>)

Store in output-var the value associated with key in map-var. If the key is not found or malformed in the list, output-var is set to <key>-NOTFOUND.

Compared to map(GET), this command is more tolerant: it never raises an error, but requires checking the sentinel value.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(FIND input_map "four" value)
# value is:
#   "4:4"
map(FIND input_map "invalid" value)
# value is:
#   "invalid-NOTFOUND"

map(SEARCH <map-var> <value> <output-list-var>)

Store in output-list-var the list of keys whose associated value matches value in map-var. Entries with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(SEARCH input_map "2" map_keys)
# map_keys is:
#   "two"
map(SEARCH input_map "" map_keys)
# map_keys is:
#   "three"

map(HAS_KEY <map-var> <key> <output-var>)

Check if the map map-var contains the given key key, and store true in output-var if found, false otherwise. Entries with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(HAS_KEY input_map "two" map_has_key)
# map_has_key is:
#   true
map(HAS_KEY input_map "five" map_has_key)
# map_has_key is:
#   false
map(HAS_KEY input_map "invalid" map_has_key)
# map_has_key is:
#   false

map(HAS_VALUE <map-var> <value> <output-var>)

Check if the map map-var contains at least one entry with value value , and store true in output-var if found, false otherwise. Entries with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(HAS_VALUE input_map "2" map_has_value)
# map_has_value is:
#   true
map(HAS_VALUE input_map "5" map_has_value)
# map_has_value is:
#   false
map(HAS_VALUE input_map "missing key" map_has_value)
# map_has_value is:
#   false

Modification

map(SET <map-var> <key> <value>)

Set the value associated with key in map-var to value. If the key exists, it is updated. Otherwise, a new entry is appended. Entries already stored in map-var with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "invalid" ":missing key")
map(SET input_map "three" "3")
map(SET input_map "four" "4:4")
# input_map is:
#   one:1;two:2;three:3;invalid;:missing key;four:4:4

map(ADD <map-var> <key> <value>)

Append a key/value pair to the map map-var, only if key does not already exist. Entries already stored in map-var with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "invalid" ":missing key")
map(ADD input_map "three" "3")
# No change, "three" already exists
map(ADD input_map "four" "4:4")
# input_map is:
#   one:1;two:2;three:;invalid;:missing key;four:4:4

map(REMOVE <map-var> <key>)

Remove a key/value pair that matches key in the map map-var. If the key does not exist, map-var is unchanged. Entries already stored in map-var with invalid format are ignored.

Example usage:

set(input_map "one:1" "two:2" "three:" "four:4:4" "invalid" ":missing key")
map(REMOVE input_map "two")
# input_map is:
#   one:1;three:;four:4:4;invalid;:missing key