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，即第一个列表元素。

Reading

list(LENGTH <list> <output variable>)

返回列表的长度。

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

从列表中返回由索引指定的元素的列表。

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

3.12 版本新增。

使用粘合字符串将列表的所有元素连接成一个字符串。要连接多个不是列表一部分的字符串，请使用 string(JOIN)。

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

3.12 版本新增。

返回给定列表的子列表。如果 <length> 为 0，则返回空列表。如果 <length> 为 -1 或列表比 <begin>+<length> 小，则返回从 <begin> 开始的列表的剩余元素。

Search

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

返回列表中指定元素的索引，如果未找到则返回 -1。

Modification

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> ...)

Changed in version 4.1: ^ 锚点现在仅匹配输入元素的开头，而不是每次重复搜索的开头。请参见策略 CMP0186。

<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> ...)

Ordering

list(REVERSE <list>)

就地反转列表内容。

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

就地按字母顺序对列表进行排序。

Added in version 3.13: 添加了 COMPARE、CASE 和 ORDER 选项。

Added in version 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

按降序对列表进行排序。