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 命令會在目前的範圍內建立新的變數值，即使列表本身實際上是在父範圍中定義的。若要將這些操作的結果向上傳播，請使用 set() 與 PARENT_SCOPE、set() 與 CACHE INTERNAL，或某些其他值傳播的方式。

注意

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) 手冊）排序字串列表，也就是說，會將連續的數字作為整數進行比較。例如：以下列表 10.0 1.1 2.1 8.0 2.0 3.1 如果選擇 NATURAL 比較，將排序為 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

以降序排序列表。