diff options
Diffstat (limited to 'Help/command/list.rst')
| -rw-r--r-- | Help/command/list.rst | 96 |
1 files changed, 63 insertions, 33 deletions
diff --git a/Help/command/list.rst b/Help/command/list.rst index bfcdf34..39e7e2a 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -21,6 +21,9 @@ Synopsis list(`APPEND`_ <list> [<element>...]) list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) 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>) @@ -33,8 +36,9 @@ Synopsis Introduction ^^^^^^^^^^^^ -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +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 :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 @@ -142,6 +146,34 @@ For more information on regular expressions see also the Inserts elements to the list to the specified location. +.. _POP_BACK: + +.. code-block:: cmake + + list(POP_BACK <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the last element's value to the given variable and removes it, +up to the last variable name given. + +.. _POP_FRONT: + +.. code-block:: cmake + + list(POP_FRONT <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the first element's value to the given variable and removes it, +up to the last variable name given. + +.. _PREPEND: + +.. code-block:: cmake + + list(PREPEND <list> [<element> ...]) + +Insert elements to the 0th position in the list. + .. _REMOVE_ITEM: .. code-block:: cmake @@ -164,7 +196,8 @@ Removes items at given indices from the list. list(REMOVE_DUPLICATES <list>) -Removes duplicated items in the list. +Removes duplicated items in the list. The relative order of items is preserved, +but if duplicates are encountered, only the first instance is preserved. .. _TRANSFORM: @@ -174,84 +207,81 @@ Removes duplicated items in the list. [OUTPUT_VARIABLE <output variable>]) Transforms the list by applying an action to all or, by specifying a -``<SELECTOR>``, to the selected elements of the list, storing result in-place -or in the specified output variable. +``<SELECTOR>``, to the selected elements of the list, storing the result +in-place or in the specified output variable. .. note:: - ``TRANSFORM`` sub-command does not change the number of elements of the + The ``TRANSFORM`` sub-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 same as before the transformation. - -``<ACTION>`` 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 other ones will remain the same as before the transformation. -The ``<ACTION>`` may be one of: +``<ACTION>`` specifies the action to apply to the elements of the list. +The actions have exactly the same semantics as sub-commands of the +:command:`string` command. ``<ACTION>`` must be one of the following: ``APPEND``, ``PREPEND``: Append, prepend specified value to each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) ``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower characters. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) ``STRIP``: Remove leading and trailing spaces from each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> STRIP ...) + list(TRANSFORM <list> STRIP ...) ``GENEX_STRIP``: Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from each element of the list. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> GENEX_STRIP ...) + list(TRANSFORM <list> 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). -.. code-block:: cmake - - list(TRANSFORM <list> REPLACE <regular_expression> - <replace_expression> ...) + .. code-block:: cmake -``<SELECTOR>`` select which elements of the list will be transformed. Only one -type of selector can be specified at a time. + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) -The ``<SELECTOR>`` may be one of: +``<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: ``AT``: Specify a list of indexes. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) ``FOR``: Specify a range with, optionally, an increment used to iterate over the range. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) ``REGEX``: Specify a regular expression. Only elements matching the regular expression will be transformed. -.. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) Ordering |