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 版本新增。

返回一个字符串，使用粘合字符串连接所有列表元素。要连接多个不属于列表的字符串，请使用 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 版本新增。

通过对列表中的所有元素或（通过指定 <SELECTOR>）对选定元素应用 <ACTION> 来转换列表，并将结果就地存储或存储在指定的输出变量中。

注意

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

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

排序

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

按降序排序列表。