From 81226c73a43ec1ff4cf1271efaeb3fefefd604c7 Mon Sep 17 00:00:00 2001 From: Marc Chevrier Date: Fri, 16 Mar 2018 10:04:44 +0100 Subject: Help: refresh list() command documentation Reformat `list` command documentation be consistent with the `string` command. --- Help/command/list.rst | 169 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 126 insertions(+), 43 deletions(-) diff --git a/Help/command/list.rst b/Help/command/list.rst index f6b75bc..e6a7069 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -1,68 +1,151 @@ list ---- +.. only:: html + + .. contents:: + List operations. +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. + +Capacity and Element access +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +LENGTH +"""""" + :: list(LENGTH ) - list(GET [ ...] - ) + +Returns the list's length. + +GET +""" + +:: + + list(GET [ ...] ) + +Returns the list of elements specified by indices from the list. + +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 ) - list(FIND ) + +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 [ ...]) - list(REMOVE_DUPLICATES ) - list(REVERSE ) - list(SORT ) -``LENGTH`` will return a given list's length. +Removes items at given indices from the list. -``GET`` will return list of elements specified by indices from the list. +REMOVE_DUPLICATES +""""""""""""""""" -``APPEND`` will append elements to the list. +:: -``FILTER`` will include or remove 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. + list(REMOVE_DUPLICATES ) -``FIND`` will return the index of the element specified in the list or -1 -if it wasn't found. +Removes duplicated items in the list. + +Sorting +^^^^^^^ + +REVERSE +""""""" -``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. + list(REVERSE ) -``REMOVE_DUPLICATES`` will remove duplicated items in the list. +Reverses the contents of the list in-place. -``REVERSE`` reverses the contents of the list in-place. +SORT +"""" -``SORT`` sorts the list in-place alphabetically. +:: + + list(SORT ) -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. -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 ```` 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. +Sorts the list in-place alphabetically. -- cgit v0.12