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

简介

列表子命令 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 命令中使用。）

不得包含数量不等的 [ 和 ] 字符，也不得以反斜杠 (\) 结束。有关详情，请参见 semicolon-separated lists。

注意

在指定索引值时，如果 <element index> 为 0 或大于 0，则从列表开头索引，0 表示第一个列表元素。如果 <element index> 为 -1 或小于 -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 版中新增。

通过对所有列表元素或（通过指定 <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

从列表中各个元素中剥离所有generator expressions。

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

按降序对列表进行排序。