list¶
Operations on semicolon-separated lists.
概要¶
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> <MODE>) 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> [...])
介紹¶
The list subcommands APPEND, INSERT, FILTER,
PREPEND, POP_BACK, POP_FRONT, REMOVE_AT,
REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and
SORT may create new values for the list within the current CMake
variable scope. Similar to the set() command, the list command
creates new variable values in the current scope, even if the list itself is
actually defined in a parent scope. To propagate the results of these
operations upwards, use set() with PARENT_SCOPE,
set() with CACHE INTERNAL, or some other means of value
propagation.
備註
A list in cmake is a ; separated group of strings. To create a
list, the set() command can be used. For example,
set(var a b c d e) creates a list with a;b;c;d;e, and
set(var "a b c d e") creates a string or a list with one item in it.
(Note that macro arguments are not variables, and therefore cannot be used
in LIST commands.)
Individual elements may not contain an unequal number of [ and ]
characters, and may not end in a backslash (\).
See semicolon-separated lists for details.
備註
When specifying index values, if <element index> is 0 or greater, it
is indexed from the beginning of the list, with 0 representing the
first list element. If <element index> is -1 or lesser, it is indexed
from the end of the list, with -1 representing the last list element.
Be careful when counting with negative indices: they do not start from
0. -0 is equivalent to 0, the first list element.
讀取¶
- list(LENGTH <list> <output variable>)¶
回傳列表的長度。
- list(GET <list> <element index> [<element index> ...] <output variable>)¶
Returns the list of elements specified by indices from the list.
- list(JOIN <list> <glue> <output variable>)¶
在 3.12 版被加入.
Returns a string joining all list's elements using the glue string. To join multiple strings, which are not part of a list, use
string(JOIN).
- list(SUBLIST <list> <begin> <length> <output variable>)¶
在 3.12 版被加入.
Returns a sublist of the given list. If
<length>is 0, an empty list will be returned. If<length>is -1 or the list is smaller than<begin>+<length>then the remaining elements of the list starting at<begin>will be returned.
搜尋¶
- list(FIND <list> <value> <output variable>)¶
Returns the index of the element specified in the list or
-1if it wasn't found.
修改¶
- list(APPEND <list> [<element> ...])¶
Appends elements to the list. If no variable named
<list>exists in the current scope its value is treated as empty and the elements are appended to that empty list.
- list(FILTER <list> <INCLUDE|EXCLUDE> <MODE>)¶
在 3.6 版被加入.
Includes or removes items from the list that match the mode's pattern.
<MODE>must be one of the following:REGEXItems will be matched against the given regular expression.
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
For more information on regular expressions, see the Regex Specification.
PREDICATESpecify a user-defined
function()as a predicate.list(FILTER <list> <INCLUDE|EXCLUDE> PREDICATE <function>)
在 4.4 版被加入.
<function>is a user-definedfunction()that acts as a unary predicate. The function must accept exactly two parameters: the input value and the name of an output variable. The function must set the output variable to a boolean value in the calling scope. The output variable is interpreted using standard CMake boolean evaluation. If the function does not set the output variable, it is an error.範例:
function(file_exists path result) if(EXISTS "${path}") set(${result} TRUE PARENT_SCOPE) else() set(${result} FALSE PARENT_SCOPE) endif() endfunction() set(candidate_files main.c missing.c utils.c) list(FILTER candidate_files INCLUDE PREDICATE file_exists)
- list(INSERT <list> <element_index> <element> [<element> ...])¶
Inserts elements to the list to the specified index. It is an error to specify an out-of-range index. Valid indexes are 0 to N where N is the length of the list, inclusive. An empty list has length 0. If no variable named
<list>exists in the current scope its value is treated as empty and the elements are inserted in that empty list.
- list(POP_BACK <list> [<out-var>...])¶
在 3.15 版被加入.
If no variable name is given, removes exactly one element. Otherwise, with N variable names provided, assign the last N elements' values to the given variables and then remove the last N values from
<list>.
- list(POP_FRONT <list> [<out-var>...])¶
在 3.15 版被加入.
If no variable name is given, removes exactly one element. Otherwise, with N variable names provided, assign the first N elements' values to the given variables and then remove the first N values from
<list>.
- list(PREPEND <list> [<element> ...])¶
在 3.15 版被加入.
Insert elements to the 0th position in the list. If no variable named
<list>exists in the current scope its value is treated as empty and the elements are prepended to that empty list.
- list(REMOVE_ITEM <list> <value> [<value> ...])¶
Removes all instances of the given items from the list.
- list(REMOVE_AT <list> <index> [<index> ...])¶
Removes items at given indices from the list.
- list(REMOVE_DUPLICATES <list>)¶
移除列表中的重複項目。項目的相對順序會保留;若遇到重複項目,只會保留第一個項目。
- list(TRANSFORM <list> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <output variable>])¶
在 3.12 版被加入.
Transforms the list by applying an
<ACTION>to all or, by specifying a<SELECTOR>, to the selected elements of the list, storing the result in-place or in the specified output variable.備註
The
TRANSFORMsub-command does not change the number of elements in the list. If a<SELECTOR>is specified, only some elements will be changed, the other ones will remain the same as before the transformation.<ACTION>specifies the action to apply to the elements of the list.<ACTION>must be one of the following:APPEND,PREPENDAppend, prepend specified value to each element of the list.
- list(TRANSFORM <list> (APPEND|PREPEND) <value> ...)¶
TOLOWER,TOUPPERConvert each element of the list to lower, upper characters.
- list(TRANSFORM <list> (TOLOWER|TOUPPER) ...)¶
STRIPRemove leading and trailing spaces from each element of the list.
- list(TRANSFORM <list> STRIP ...)¶
GENEX_STRIPStrip any
generator expressionsfrom each element of the list.- list(TRANSFORM <list> GENEX_STRIP ...)¶
REPLACEMatch the regular expression as many times as possible and substitute the replacement expression for the match for each element of the list (same semantic as
string(REGEX REPLACE)).- list(TRANSFORM <list> REPLACE <regular_expression> <replace_expression> ...)¶
在 4.1 版的變更: The
^anchor now matches only at the beginning of the input element instead of the beginning of each repeated search. See policyCMP0186.APPLYInvoke a user-defined
function()for each element of the list. The function must accept exactly two parameters: the input value and the name of an output variable. The function must set the output variable in the calling scope.- list(TRANSFORM <list> APPLY <function> ...)¶
在 4.4 版被加入.
<function>is afunction()with exactly two formal parameters. Set the output variable viaset(<variable> <value> PARENT_SCOPE):function(<function> <input> <output>) # Transform <input>, store result in ${<output>} set(${<output>} "<result>" PARENT_SCOPE) endfunction()
Before each invocation, the output variable is unset in the calling scope to prevent stale values.
範例:
function(make_absolute in out) cmake_path(ABSOLUTE_PATH in BASE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}") set(${out} "${in}" PARENT_SCOPE) endfunction() set(mylist main.c utils.c io.c) list(TRANSFORM mylist APPLY make_absolute) # mylist is now absolute paths relative to CMAKE_CURRENT_SOURCE_DIR
<SELECTOR>determines which elements of the list will be transformed. Only one type of selector can be specified at a time. When given,<SELECTOR>must be one of the following:ATSpecify a list of indexes.
list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
FORSpecify a range with, optionally, an increment used to iterate over the range.
list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
REGEX指定常規表達式。只有符合常規表達式的元素才會被變換。
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
PREDICATESpecify a user-defined
function()as a predicate. Only elements for which the function returns a true value will be transformed.list(TRANSFORM <list> <ACTION> PREDICATE <function> ...)
在 4.4 版被加入.
<function>is a user-definedfunction()with exactly two formal parameters: the input value and the name of an output variable. The function must set the output variable to a boolean value. Standard CMake boolean evaluation is used. If the function does not set the output variable, it is an error. The function is evaluated for each element in turn, immediately before that element would be transformed.範例:
function(is_relative path result) if(NOT IS_ABSOLUTE "${path}") set(${result} TRUE PARENT_SCOPE) else() set(${result} FALSE PARENT_SCOPE) endif() endfunction() set(search_paths /usr/include src lib /opt/lib) list(TRANSFORM search_paths PREPEND "${CMAKE_CURRENT_SOURCE_DIR}/" PREDICATE is_relative)
Ordering¶
- list(REVERSE <list>)¶
就地反轉列表的內容。
- list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])¶
- list(SORT <list> COMPARATOR <function> [CASE <case>] [ORDER <order>])
就地依字母順序排序列表。
在 3.13 版被加入: Added the
COMPARE,CASE, andORDERoptions.在 3.18 版被加入: Added the
COMPARE NATURALoption.Use the
COMPAREkeyword to select the comparison method for sorting. The<compare>option should be one of:STRINGSorts a list of strings alphabetically. This is the default behavior if the
COMPAREoption is not given.FILE_BASENAMESorts a list of pathnames of files by their basenames.
NATURALSorts a list of strings using natural order (see
strverscmp(3)manual), i.e. such that contiguous digits are compared as whole numbers. For example: the following list 10.0 1.1 2.1 8.0 2.0 3.1 will be sorted as 1.1 2.0 2.1 3.1 8.0 10.0 if theNATURALcomparison is selected where it will be sorted as 1.1 10.0 2.0 2.1 3.1 8.0 with theSTRINGcomparison.
Use the
CASEkeyword to select a case sensitive or case insensitive sort mode. The<case>option should be one of:SENSITIVE以區分大小寫的方式排序列表項目。若未指定
CASE選項,這是默認行為。INSENSITIVEList items are sorted case insensitively. The order of items which differ only by upper/lowercase is not specified.
To control the sort order, the
ORDERkeyword can be given. The<order>option should be one of:ASCENDINGSorts the list in ascending order. This is the default behavior when the
ORDERoption is not given.DESCENDING以遞減順序排序列表。
Instead of the built-in
COMPAREmethods, a user-defined comparisonfunction()may be used with theCOMPARATORkeyword.在 4.4 版被加入.
COMPARATORis mutually exclusive withCOMPARE. TheCASEandORDERoptions may still be used alongsideCOMPARATOR: theCASEfilter is applied to both values before they are passed to the function, andORDER DESCENDINGreverses the comparison by swapping the two arguments.函數必須恰好接受三個參數:兩個輸入值,以及一個輸出變數名稱。函數必須在呼叫端作用域中,將輸出變數設為布林值(若第一個值應排在第二個值之前,則設為
TRUE;否則設為FALSE)。若函數未設定輸出變數,即為錯誤。比較器必須定義嚴格弱序。具體而言:
It must return
FALSEwhen comparing an element to itself (irreflexivity).If it returns
TRUEfor(a, b), it must returnFALSEfor(b, a)(asymmetry).
An error is raised if the comparator violates these requirements.
範例:
function(version_less a b result) if("${a}" VERSION_LESS "${b}") set(${result} TRUE PARENT_SCOPE) else() set(${result} FALSE PARENT_SCOPE) endif() endfunction() set(versions 3.1 1.2 2.0 1.10) list(SORT versions COMPARATOR version_less) # versions is now: 1.2;1.10;2.0;3.1