CMake/Help/command/list.rst
Michael Scott c3f40f4fd9 Help: Improve formatting of command documentation
Use inline reStructuredText markup and add cross-references in more
places.
2015-06-08 16:28:31 -04:00

62 lines
2.4 KiB
ReStructuredText

list
----
List operations.
::
list(LENGTH <list> <output variable>)
list(GET <list> <element index> [<element index> ...]
<output variable>)
list(APPEND <list> [<element> ...])
list(FIND <list> <value> <output variable>)
list(INSERT <list> <element_index> <element> [<element> ...])
list(REMOVE_ITEM <list> <value> [<value> ...])
list(REMOVE_AT <list> <index> [<index> ...])
list(REMOVE_DUPLICATES <list>)
list(REVERSE <list>)
list(SORT <list>)
``LENGTH`` will return a given list's length.
``GET`` will return list of elements specified by indices from the list.
``APPEND`` will append elements to the list.
``FIND`` will return the index of the element specified in the list or -1
if it wasn't found.
``INSERT`` will insert elements to the list to the specified location.
``REMOVE_AT`` and ``REMOVE_ITEM`` will remove items from the list. The
difference is that ``REMOVE_ITEM`` will remove the given items, while
``REMOVE_AT`` will remove the items at the given indices.
``REMOVE_DUPLICATES`` will remove duplicated items in the list.
``REVERSE`` reverses the contents of the list in-place.
``SORT`` sorts the list in-place alphabetically.
The list subcommands ``APPEND``, ``INSERT``, ``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.
NOTES: 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.)
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.