1list 2---- 3 4List operations. 5 6Synopsis 7^^^^^^^^ 8 9.. parsed-literal:: 10 11 `Reading`_ 12 list(`LENGTH`_ <list> <out-var>) 13 list(`GET`_ <list> <element index> [<index> ...] <out-var>) 14 list(`JOIN`_ <list> <glue> <out-var>) 15 list(`SUBLIST`_ <list> <begin> <length> <out-var>) 16 17 `Search`_ 18 list(`FIND`_ <list> <value> <out-var>) 19 20 `Modification`_ 21 list(`APPEND`_ <list> [<element>...]) 22 list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) 23 list(`INSERT`_ <list> <index> [<element>...]) 24 list(`POP_BACK`_ <list> [<out-var>...]) 25 list(`POP_FRONT`_ <list> [<out-var>...]) 26 list(`PREPEND`_ <list> [<element>...]) 27 list(`REMOVE_ITEM`_ <list> <value>...) 28 list(`REMOVE_AT`_ <list> <index>...) 29 list(`REMOVE_DUPLICATES`_ <list>) 30 list(`TRANSFORM`_ <list> <ACTION> [...]) 31 32 `Ordering`_ 33 list(`REVERSE`_ <list>) 34 list(`SORT`_ <list> [...]) 35 36Introduction 37^^^^^^^^^^^^ 38 39The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``, 40``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``, 41``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create 42new values for the list within the current CMake variable scope. Similar to 43the :command:`set` command, the LIST command creates new variable values in 44the current scope, even if the list itself is actually defined in a parent 45scope. To propagate the results of these operations upwards, use 46:command:`set` with ``PARENT_SCOPE``, :command:`set` with 47``CACHE INTERNAL``, or some other means of value propagation. 48 49.. note:: 50 51 A list in cmake is a ``;`` separated group of strings. To create a 52 list the set command can be used. For example, ``set(var a b c d e)`` 53 creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a 54 string or a list with one item in it. (Note macro arguments are not 55 variables, and therefore cannot be used in LIST commands.) 56 57.. note:: 58 59 When specifying index values, if ``<element index>`` is 0 or greater, it 60 is indexed from the beginning of the list, with 0 representing the 61 first list element. If ``<element index>`` is -1 or lesser, it is indexed 62 from the end of the list, with -1 representing the last list element. 63 Be careful when counting with negative indices: they do not start from 64 0. -0 is equivalent to 0, the first list element. 65 66Reading 67^^^^^^^ 68 69.. _LENGTH: 70 71.. code-block:: cmake 72 73 list(LENGTH <list> <output variable>) 74 75Returns the list's length. 76 77.. _GET: 78 79.. code-block:: cmake 80 81 list(GET <list> <element index> [<element index> ...] <output variable>) 82 83Returns the list of elements specified by indices from the list. 84 85.. _JOIN: 86 87.. code-block:: cmake 88 89 list(JOIN <list> <glue> <output variable>) 90 91.. versionadded:: 3.12 92 93Returns a string joining all list's elements using the glue string. 94To join multiple strings, which are not part of a list, use ``JOIN`` operator 95from :command:`string` command. 96 97.. _SUBLIST: 98 99.. code-block:: cmake 100 101 list(SUBLIST <list> <begin> <length> <output variable>) 102 103.. versionadded:: 3.12 104 105Returns a sublist of the given list. 106If ``<length>`` is 0, an empty list will be returned. 107If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then 108the remaining elements of the list starting at ``<begin>`` will be returned. 109 110Search 111^^^^^^ 112 113.. _FIND: 114 115.. code-block:: cmake 116 117 list(FIND <list> <value> <output variable>) 118 119Returns the index of the element specified in the list or -1 120if it wasn't found. 121 122Modification 123^^^^^^^^^^^^ 124 125.. _APPEND: 126 127.. code-block:: cmake 128 129 list(APPEND <list> [<element> ...]) 130 131Appends elements to the list. 132 133.. _FILTER: 134 135.. code-block:: cmake 136 137 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) 138 139.. versionadded:: 3.6 140 141Includes or removes items from the list that match the mode's pattern. 142In ``REGEX`` mode, items will be matched against the given regular expression. 143 144For more information on regular expressions look under 145:ref:`string(REGEX) <Regex Specification>`. 146 147.. _INSERT: 148 149.. code-block:: cmake 150 151 list(INSERT <list> <element_index> <element> [<element> ...]) 152 153Inserts elements to the list to the specified location. 154 155.. _POP_BACK: 156 157.. code-block:: cmake 158 159 list(POP_BACK <list> [<out-var>...]) 160 161.. versionadded:: 3.15 162 163If no variable name is given, removes exactly one element. Otherwise, 164with `N` variable names provided, assign the last `N` elements' values 165to the given variables and then remove the last `N` values from 166``<list>``. 167 168.. _POP_FRONT: 169 170.. code-block:: cmake 171 172 list(POP_FRONT <list> [<out-var>...]) 173 174.. versionadded:: 3.15 175 176If no variable name is given, removes exactly one element. Otherwise, 177with `N` variable names provided, assign the first `N` elements' values 178to the given variables and then remove the first `N` values from 179``<list>``. 180 181.. _PREPEND: 182 183.. code-block:: cmake 184 185 list(PREPEND <list> [<element> ...]) 186 187.. versionadded:: 3.15 188 189Insert elements to the 0th position in the list. 190 191.. _REMOVE_ITEM: 192 193.. code-block:: cmake 194 195 list(REMOVE_ITEM <list> <value> [<value> ...]) 196 197Removes all instances of the given items from the list. 198 199.. _REMOVE_AT: 200 201.. code-block:: cmake 202 203 list(REMOVE_AT <list> <index> [<index> ...]) 204 205Removes items at given indices from the list. 206 207.. _REMOVE_DUPLICATES: 208 209.. code-block:: cmake 210 211 list(REMOVE_DUPLICATES <list>) 212 213Removes duplicated items in the list. The relative order of items is preserved, 214but if duplicates are encountered, only the first instance is preserved. 215 216.. _TRANSFORM: 217 218.. code-block:: cmake 219 220 list(TRANSFORM <list> <ACTION> [<SELECTOR>] 221 [OUTPUT_VARIABLE <output variable>]) 222 223.. versionadded:: 3.12 224 225Transforms the list by applying an action to all or, by specifying a 226``<SELECTOR>``, to the selected elements of the list, storing the result 227in-place or in the specified output variable. 228 229.. note:: 230 231 The ``TRANSFORM`` sub-command does not change the number of elements in the 232 list. If a ``<SELECTOR>`` is specified, only some elements will be changed, 233 the other ones will remain the same as before the transformation. 234 235``<ACTION>`` specifies the action to apply to the elements of the list. 236The actions have exactly the same semantics as sub-commands of the 237:command:`string` command. ``<ACTION>`` must be one of the following: 238 239``APPEND``, ``PREPEND``: Append, prepend specified value to each element of 240the list. 241 242 .. code-block:: cmake 243 244 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) 245 246``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower 247characters. 248 249 .. code-block:: cmake 250 251 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) 252 253``STRIP``: Remove leading and trailing spaces from each element of the 254list. 255 256 .. code-block:: cmake 257 258 list(TRANSFORM <list> STRIP ...) 259 260``GENEX_STRIP``: Strip any 261:manual:`generator expressions <cmake-generator-expressions(7)>` from each 262element of the list. 263 264 .. code-block:: cmake 265 266 list(TRANSFORM <list> GENEX_STRIP ...) 267 268``REPLACE``: Match the regular expression as many times as possible and 269substitute the replacement expression for the match for each element 270of the list 271(Same semantic as ``REGEX REPLACE`` from :command:`string` command). 272 273 .. code-block:: cmake 274 275 list(TRANSFORM <list> REPLACE <regular_expression> 276 <replace_expression> ...) 277 278``<SELECTOR>`` determines which elements of the list will be transformed. 279Only one type of selector can be specified at a time. When given, 280``<SELECTOR>`` must be one of the following: 281 282``AT``: Specify a list of indexes. 283 284 .. code-block:: cmake 285 286 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) 287 288``FOR``: Specify a range with, optionally, an increment used to iterate over 289the range. 290 291 .. code-block:: cmake 292 293 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) 294 295``REGEX``: Specify a regular expression. Only elements matching the regular 296expression will be transformed. 297 298 .. code-block:: cmake 299 300 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) 301 302 303Ordering 304^^^^^^^^ 305 306.. _REVERSE: 307 308.. code-block:: cmake 309 310 list(REVERSE <list>) 311 312Reverses the contents of the list in-place. 313 314.. _SORT: 315 316.. code-block:: cmake 317 318 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) 319 320Sorts the list in-place alphabetically. 321 322.. versionadded:: 3.13 323 Added the ``COMPARE``, ``CASE``, and ``ORDER`` options. 324 325.. versionadded:: 3.18 326 Added the ``COMPARE NATURAL`` option. 327 328Use the ``COMPARE`` keyword to select the comparison method for sorting. 329The ``<compare>`` option should be one of: 330 331* ``STRING``: Sorts a list of strings alphabetically. This is the 332 default behavior if the ``COMPARE`` option is not given. 333* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames. 334* ``NATURAL``: Sorts a list of strings using natural order 335 (see ``strverscmp(3)`` manual), i.e. such that contiguous digits 336 are compared as whole numbers. 337 For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1` 338 will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL`` 339 comparison is selected where it will be sorted as 340 `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison. 341 342Use the ``CASE`` keyword to select a case sensitive or case insensitive 343sort mode. The ``<case>`` option should be one of: 344 345* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is 346 the default behavior if the ``CASE`` option is not given. 347* ``INSENSITIVE``: List items are sorted case insensitively. The order of 348 items which differ only by upper/lowercase is not specified. 349 350To control the sort order, the ``ORDER`` keyword can be given. 351The ``<order>`` option should be one of: 352 353* ``ASCENDING``: Sorts the list in ascending order. This is the default 354 behavior when the ``ORDER`` option is not given. 355* ``DESCENDING``: Sorts the list in descending order. 356