list

對以分號分隔的列表進行操作。

概要

Reading
  list(LENGTH <list> <out-var>)
  list(GET <list> <element index> [<index> ...] <out-var>)
  list(JOIN <list> <glue> <out-var>)
  list(SUBLIST <list> <begin> <length> <out-var>)

Search
  list(FIND <list> <value> <out-var>)

Modification
  list(APPEND <list> [<element>...])
  list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
  list(INSERT <list> <index> [<element>...])
  list(POP_BACK <list> [<out-var>...])
  list(POP_FRONT <list> [<out-var>...])
  list(PREPEND <list> [<element>...])
  list(REMOVE_ITEM <list> <value>...)
  list(REMOVE_AT <list> <index>...)
  list(REMOVE_DUPLICATES <list>)
  list(TRANSFORM <list> <ACTION> [...])

Ordering
  list(REVERSE <list>)
  list(SORT <list> [...])

簡介

list 子命令 APPEND、 INSERT、 FILTER、 PREPEND、 POP_BACK、 POP_FRONT、 REMOVE_AT、 REMOVE_ITEM、 REMOVE_DUPLICATES、 REVERSE 和 SORT 可以在目前的 CMake 變數範圍內建立列表的新值。類似於 set() 命令，即使列表本身實際上是在父範圍中定義的，list 命令也會在目前的範圍中建立新的變數值。若要向上傳播這些操作的結果，請搭配 PARENT_SCOPE 使用 set()、搭配 CACHE INTERNAL 使用 set()，或使用其他值傳播方式。

注意

cmake 中的列表是以 ; 分隔的字串群組。若要建立列表，可以使用 set() 命令。例如，set(var a b c d e) 會建立一個包含 a;b;c;d;e 的列表，而 set(var "a b c d e") 則會建立一個字串或一個包含一個項目的列表。（請注意，巨集引數不是變數，因此不能在 LIST 命令中使用。）

個別元素可能不包含數量不相等的 [ 和 ] 字元，並且不得以反斜線 (\) 結尾。請參閱以分號分隔的列表以取得詳細資訊。

注意

在指定索引值時，如果 <element index> 為 0 或更大，則會從列表的開頭開始索引，其中 0 代表第一個列表元素。如果 <element index> 為 -1 或更小，則會從列表的結尾開始索引，其中 -1 代表最後一個列表元素。使用負索引計數時請小心：它們不是從 0 開始。-0 等同於 0，即第一個列表元素。

讀取

list(LENGTH <list> <output variable>)

傳回列表的長度。

list(GET <list> <element index> [<element index> ...] <output variable>)

從列表中傳回索引指定的元素列表。

list(JOIN <list> <glue> <output variable>)

在 3.12 版本中新增。

傳回一個字串，該字串使用 glue 字串聯結所有列表的元素。若要聯結多個非列表一部分的字串，請使用 string(JOIN)。

list(SUBLIST <list> <begin> <length> <output variable>)

在 3.12 版本中新增。

傳回給定列表的子列表。如果 <length> 為 0，則會傳回空列表。如果 <length> 為 -1 或列表小於 <begin>+<length>，則會傳回從 <begin> 開始的列表剩餘元素。

搜尋

list(FIND <list> <value> <output variable>)

傳回列表中指定元素的索引，如果找不到則傳回 -1。

修改

list(APPEND <list> [<element> ...])

將元素附加到列表。如果目前範圍中不存在名為 <list> 的變數，則其值會被視為空，並且元素會附加到該空列表中。

list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)

在 3.6 版本中新增。

包括或移除列表中與模式相符的項目。在 REGEX 模式下，項目將與給定的正規表示式進行比對。

有關正規表示式的更多資訊，請參閱 string(REGEX)。

list(INSERT <list> <element_index> <element> [<element> ...])

將元素插入列表中指定的索引處。指定超出範圍的索引是錯誤的。有效的索引為 0 到 N，其中 N 是列表的長度（包含）。空列表的長度為 0。如果目前範圍中不存在名為 <list> 的變數，則其值會被視為空，並且元素會插入到該空列表中。

list(POP_BACK <list> [<out-var>...])

在 3.15 版本中新增。

如果未給定變數名稱，則只移除一個元素。否則，如果提供了 N 個變數名稱，則將最後 N 個元素的值指派給給定的變數，然後從 <list> 中移除最後 N 個值。

list(POP_FRONT <list> [<out-var>...])

在 3.15 版本中新增。

如果未給定變數名稱，則只移除一個元素。否則，如果提供了 N 個變數名稱，則將前 N 個元素的值指派給給定的變數，然後從 <list> 中移除前 N 個值。

list(PREPEND <list> [<element> ...])

在 3.15 版本中新增。

將元素插入列表中的第 0 個位置。如果目前範圍中不存在名為 <list> 的變數，則其值會被視為空，並且元素會前置到該空列表中。

list(REMOVE_ITEM <list> <value> [<value> ...])

從列表中移除給定項目的所有執行個體。

list(REMOVE_AT <list> <index> [<index> ...])

從列表中移除給定索引處的項目。

list(REMOVE_DUPLICATES <list>)

移除列表中重複的項目。項目的相對順序會保留，但如果遇到重複項目，則只會保留第一個執行個體。

list(TRANSFORM <list> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <output variable>])

在 3.12 版本中新增。

透過將 <ACTION> 應用於列表的所有元素，或透過指定 <SELECTOR> 應用於列表的選定元素來轉換列表，並將結果儲存在原地或指定的輸出變數中。

注意

TRANSFORM 子命令不會變更列表中元素的數量。如果指定了 <SELECTOR>，則只會變更某些元素，其他元素將與轉換前保持相同。

<ACTION> 指定要應用於列表元素的操作。這些操作與 string() 命令的子命令具有完全相同的語意。<ACTION> 必須是下列其中一項

APPEND、 PREPEND

將指定的值附加、前置到列表的每個元素。

list(TRANSFORM <list> (APPEND|PREPEND) <value> ...)

TOLOWER、 TOUPPER

將列表的每個元素轉換為小寫、大寫字元。

list(TRANSFORM <list> (TOLOWER|TOUPPER) ...)

STRIP

從列表的每個元素中移除開頭和結尾的空格。

list(TRANSFORM <list> STRIP ...)

GENEX_STRIP

從列表的每個元素中移除任何 產生器運算式。

list(TRANSFORM <list> GENEX_STRIP ...)

REPLACE

比對正規表示式盡可能多次，並將取代運算式取代為列表中每個元素的比對項（與 string(REGEX REPLACE) 語意相同）。

list(TRANSFORM <list> REPLACE <regular_expression> <replace_expression> ...)

<SELECTOR> 決定將轉換列表中的哪些元素。一次只能指定一種選取器類型。如果給定，<SELECTOR> 必須是下列其中一項

AT

指定索引列表。

list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)

FOR

指定一個範圍，並可選擇性地指定用於逐次迭代範圍的增量。

list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)

REGEX

指定正規表示式。只會轉換與正規表示式相符的元素。

list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)

排序

list(REVERSE <list>)

就地反轉列表的內容。

list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])

依字母順序就地排序列表。

在 3.13 版本中新增：新增了 COMPARE、 CASE 和 ORDER 選項。

在 3.18 版本中新增：新增了 COMPARE NATURAL 選項。

使用 COMPARE 關鍵字來選取排序的比較方法。<compare> 選項應為下列其中一項

STRING

依字母順序排序字串列表。如果未給定 COMPARE 選項，這是預設行為。

FILE_BASENAME

依檔案的基本名稱排序檔案路徑名稱列表。

NATURAL

使用自然順序排序字串列表（請參閱 strverscmp(3) 手冊），亦即，將連續的數字視為整數進行比較。例如：如果選取 NATURAL 比較，則下列列表 10.0 1.1 2.1 8.0 2.0 3.1 將排序為 1.1 2.0 2.1 3.1 8.0 10.0，而使用 STRING 比較則會排序為 1.1 10.0 2.0 2.1 3.1 8.0。

使用 CASE 關鍵字來選取區分大小寫或不區分大小寫的排序模式。<case> 選項應為下列其中一項

SENSITIVE

列表項目會以區分大小寫的方式排序。如果未給定 CASE 選項，這是預設行為。

INSENSITIVE

列表項目會以不區分大小寫的方式排序。僅因大小寫而異的項目的順序未指定。

若要控制排序順序，可以給定 ORDER 關鍵字。<order> 選項應為下列其中一項

ASCENDING

以遞增順序排序列表。當未給定 ORDER 選項時，這是預設行為。

DESCENDING

以遞減順序排序列表。