summaryrefslogtreecommitdiffstats
path: root/Help/command/string.rst
diff options
context:
space:
mode:
authorNikita Nemkin <nikita@nemkin.ru>2020-11-07 20:30:30 (GMT)
committerNikita Nemkin <nikita@nemkin.ru>2020-11-09 15:51:57 (GMT)
commitc705279bae45c85b689febd66d5437d9ec05c9b9 (patch)
treef64bca14f17a902a96d67a30357df3d1e6c745eb /Help/command/string.rst
parent63a1917d098922b59bbba8fdeb42519363d5ba0d (diff)
downloadCMake-c705279bae45c85b689febd66d5437d9ec05c9b9.zip
CMake-c705279bae45c85b689febd66d5437d9ec05c9b9.tar.gz
CMake-c705279bae45c85b689febd66d5437d9ec05c9b9.tar.bz2
Help: Add `.. versionadded` directives to commands documentation
This change ony concerns directives that appear in the document body. The guidelines for inserting version directives: * Baseline version is CMake 3.0, i.e. directives start at 3.1. * Always use `.. versionadded::` directive, avoid ad-hoc version references. Exception: policy pages. * For new command signatures, put `versionadded` on a separate line after the signature. * For a group of new signatures in a new document section, a single version note at the beginning of the section is sufficient. * For new options, put `versionadded` on a separate line before option description. * If all the option descriptions in the list are short one-liners, it's fine to put `versionadded` on the same line as the description. * If multiple option descriptions in close proximity would have the same ..versionadded directive, consider adding a single directive after the list, mentioning all added options. * For compact value lists and sub-option lists, put a single `versionadded` directive after the list mentioning all additions. * When a change is described in a single paragraph, put `versionadded` into that paragraph. * When only part of the paragraph has changed, separate the changed part if it doesn't break the flow. Otherwise, write a follow-up clarification paragraph and apply version directive to that. * When multiple version directives are close by, order earlier additions before later additions. * Indent related lists and code blocks to include them in the scope of `versionadded` directive. Issue: #19715
Diffstat (limited to 'Help/command/string.rst')
-rw-r--r--Help/command/string.rst58
1 files changed, 46 insertions, 12 deletions
diff --git a/Help/command/string.rst b/Help/command/string.rst
index 51f8d82..9b459b4 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -170,10 +170,12 @@ The following characters have special meaning in regular expressions:
Matches a pattern on either side of the ``|``
``()``
Saves a matched subexpression, which can be referenced
- in the ``REGEX REPLACE`` operation. Additionally it is saved
- by all regular expression-related commands, including
- e.g. :command:`if(MATCHES)`, in the variables
- :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9.
+ in the ``REGEX REPLACE`` operation.
+
+ .. versionadded:: 3.9
+ All regular expression-related commands, including e.g.
+ :command:`if(MATCHES)`, save subgroup matches in the variables
+ :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9.
``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|``
has lower precedence than concatenation. This means that the regular
@@ -205,6 +207,8 @@ Manipulation
string(APPEND <string_variable> [<input>...])
+.. versionadded:: 3.4
+
Append all the ``<input>`` arguments to the string.
.. _PREPEND:
@@ -213,6 +217,8 @@ Append all the ``<input>`` arguments to the string.
string(PREPEND <string_variable> [<input>...])
+.. versionadded:: 3.10
+
Prepend all the ``<input>`` arguments to the string.
.. _CONCAT:
@@ -230,6 +236,8 @@ the result in the named ``<output_variable>``.
string(JOIN <glue> <output_variable> [<input>...])
+.. versionadded:: 3.12
+
Join all the ``<input>`` arguments together using the ``<glue>``
string and store the result in the named ``<output_variable>``.
@@ -271,16 +279,15 @@ result stored in ``<output_variable>`` will *not* be the number of characters.
Store in an ``<output_variable>`` a substring of a given ``<string>``. If
``<length>`` is ``-1`` the remainder of the string starting at ``<begin>``
-will be returned. If ``<string>`` is shorter than ``<length>`` then the
-end of the string is used instead.
+will be returned.
+
+.. versionadded:: 3.2
+ If ``<string>`` is shorter than ``<length>`` then the end of the string
+ is used instead. Previous versions of CMake reported an error in this case.
Both ``<begin>`` and ``<length>`` are counted in bytes, so care must
be exercised if ``<string>`` could contain multi-byte characters.
-.. note::
- CMake 3.1 and below reported an error if ``<length>`` pointed past
- the end of ``<string>``.
-
.. _STRIP:
.. code-block:: cmake
@@ -296,6 +303,8 @@ leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
+.. versionadded:: 3.1
+
Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
from the input ``<string>`` and store the result in the ``<output_variable>``.
@@ -305,6 +314,8 @@ from the input ``<string>`` and store the result in the ``<output_variable>``.
string(REPEAT <string> <count> <output_variable>)
+.. versionadded:: 3.15
+
Produce the output string as the input ``<string>`` repeated ``<count>`` times.
Comparison
@@ -323,6 +334,9 @@ Comparison
Compare the strings and store true or false in the ``<output_variable>``.
+.. versionadded:: 3.7
+ Added ``LESS_EQUAL`` and ``GREATER_EQUAL`` options.
+
.. _`Supported Hash Algorithms`:
Hashing
@@ -358,6 +372,9 @@ The supported ``<HASH>`` algorithm names are:
``SHA3_512``
Keccak SHA-3.
+.. versionadded:: 3.8
+ Added ``SHA3`` hash algorithms.
+
Generation
^^^^^^^^^^
@@ -375,6 +392,8 @@ Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
+.. versionadded:: 3.18
+
Convert each byte in the input ``<string>`` to its hexadecimal representation
and store the concatenated hex digits in the ``<output_variable>``. Letters in
the output (``a`` through ``f``) are in lowercase.
@@ -451,6 +470,18 @@ specifiers:
%y The last two digits of the current year (00-99)
%Y The current year.
+.. versionadded:: 3.6
+ ``%s`` format specifier (UNIX time).
+
+.. versionadded:: 3.7
+ ``%a`` and ``%b`` format specifiers (abbreviated month and weekday names).
+
+.. versionadded:: 3.8
+ ``%%`` specifier (literal ``%``).
+
+.. versionadded:: 3.7
+ ``%A`` and ``%B`` format specifiers (full month and weekday names).
+
Unknown format specifiers will be ignored and copied to the output
as-is.
@@ -461,8 +492,7 @@ If no explicit ``<format_string>`` is given, it will default to:
%Y-%m-%dT%H:%M:%S for local time.
%Y-%m-%dT%H:%M:%SZ for UTC.
-.. note::
-
+.. versionadded:: 3.8
If the ``SOURCE_DATE_EPOCH`` environment variable is set,
its value will be used instead of the current time.
See https://reproducible-builds.org/specs/source-date-epoch/ for details.
@@ -474,6 +504,8 @@ If no explicit ``<format_string>`` is given, it will default to:
string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER])
+.. versionadded:: 3.1
+
Create a universally unique identifier (aka GUID) as per RFC4122
based on the hash of the combined values of ``<namespace>``
(which itself has to be a valid UUID) and ``<name>``.
@@ -489,6 +521,8 @@ with the optional ``UPPER`` flag.
JSON
^^^^
+.. versionadded:: 3.19
+
Functionality for querying a JSON string.
.. note::