list ---- List operations. Synopsis ^^^^^^^^ .. parsed-literal:: `Reading`_ list(`LENGTH`_ ) list(`GET`_ [ ...] ) list(`JOIN`_ ) list(`SUBLIST`_ ) `Search`_ list(`FIND`_ ) `Modification`_ list(`APPEND`_ [...]) list(`FILTER`_ {INCLUDE | EXCLUDE} REGEX ) list(`INSERT`_ [...]) list(`REMOVE_ITEM`_ ...) list(`REMOVE_AT`_ ...) list(`REMOVE_DUPLICATES`_ ) list(`TRANSFORM`_ [...]) `Ordering`_ list(`REVERSE`_ ) list(`SORT`_ [...]) Introduction ^^^^^^^^^^^^ The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``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 :command:`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 :command:`set` with ``PARENT_SCOPE``, :command:`set` with ``CACHE INTERNAL``, or some other means of value propagation. .. note:: 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 macro arguments are not variables, and therefore cannot be used in LIST commands.) .. note:: When specifying index values, if ```` is 0 or greater, it is indexed from the beginning of the list, with 0 representing the first list element. If ```` 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. Reading ^^^^^^^ .. _LENGTH: :: list(LENGTH ) Returns the list's length. .. _GET: :: list(GET [ ...] ) Returns the list of elements specified by indices from the list. .. _JOIN: :: list(JOIN ) Returns a string joining all list's elements using the glue string. To join multiple strings, which are not part of a list, use ``JOIN`` operator from :command:`string` command. .. _SUBLIST: :: list(SUBLIST ) Returns a sublist of the given list. If ```` is 0, an empty list will be returned. If ```` is -1 or the list is smaller than ``+`` then the remaining elements of the list starting at ```` will be returned. Search ^^^^^^ .. _FIND: :: list(FIND ) Returns the index of the element specified in the list or -1 if it wasn't found. Modification ^^^^^^^^^^^^ .. _APPEND: :: list(APPEND [ ...]) Appends elements to the list. .. _FILTER: :: list(FILTER REGEX ) Includes or removes items from the list that match the mode's pattern. In ``REGEX`` mode, items will be matched against the given regular expression. For more information on regular expressions see also the :command:`string` command. .. _INSERT: :: list(INSERT [ ...]) Inserts elements to the list to the specified location. .. _REMOVE_ITEM: :: list(REMOVE_ITEM [ ...]) Removes the given items from the list. .. _REMOVE_AT: :: list(REMOVE_AT [ ...]) Removes items at given indices from the list. .. _REMOVE_DUPLICATES: :: list(REMOVE_DUPLICATES ) Removes duplicated items in the list. .. _TRANSFORM: :: list(TRANSFORM [] [OUTPUT_VARIABLE ]) Transforms the list by applying an action to all or, by specifying a ````, to the selected elements of the list, storing result in-place or in the specified output variable. .. note:: ``TRANSFORM`` sub-command does not change the number of elements of the list. If a ```` is specified, only some elements will be changed, the other ones will remain same as before the transformation. ```` specify the action to apply to the elements of list. The actions have exactly the same semantics as sub-commands of :command:`string` command. The ```` may be one of: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of the list. :: list(TRANSFORM ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower characters. :: list(TRANSFORM ...) ``STRIP``: Remove leading and trailing spaces from each element of the list. :: list(TRANSFORM STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions ` from each element of the list. :: list(TRANSFORM GENEX_STRIP ...) ``REPLACE``: Match 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 ``REGEX REPLACE`` from :command:`string` command). :: list(TRANSFORM REPLACE ...) ```` select which elements of the list will be transformed. Only one type of selector can be specified at a time. The ```` may be one of: ``AT``: Specify a list of indexes. :: list(TRANSFORM AT [ ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over the range. :: list(TRANSFORM FOR [] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular expression will be transformed. :: list(TRANSFORM REGEX ...) Ordering ^^^^^^^^ .. _REVERSE: :: list(REVERSE ) Reverses the contents of the list in-place. .. _SORT: :: list(SORT [COMPARE ] [CASE ] [ORDER ]) Sorts the list in-place alphabetically. Use the ``COMPARE`` keyword to select the comparison method for sorting. The ```` option should be one of: * ``STRING``: Sorts a list of strings alphabetically. This is the default behavior if the ``COMPARE`` option is not given. * ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames. Use the ``CASE`` keyword to select a case sensitive or case insensitive sort mode. The ```` option should be one of: * ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is the default behavior if the ``CASE`` option is not given. * ``INSENSITIVE``: List items are sorted case insensitively. The order of items which differ only by upper/lowercase is not specified. To control the sort order, the ``ORDER`` keyword can be given. The ```` option should be one of: * ``ASCENDING``: Sorts the list in ascending order. This is the default behavior when the ``ORDER`` option is not given. * ``DESCENDING``: Sorts the list in descending order.