diff options
Diffstat (limited to 'Help/command/string.rst')
| -rw-r--r-- | Help/command/string.rst | 663 |
1 files changed, 663 insertions, 0 deletions
diff --git a/Help/command/string.rst b/Help/command/string.rst new file mode 100644 index 0000000..c24b9bc --- /dev/null +++ b/Help/command/string.rst @@ -0,0 +1,663 @@ +string +------ + +String operations. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Search and Replace`_ + string(`FIND`_ <string> <substring> <out-var> [...]) + string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) + string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) + string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) + string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) + + `Manipulation`_ + string(`APPEND`_ <string-var> [<input>...]) + string(`PREPEND`_ <string-var> [<input>...]) + string(`CONCAT`_ <out-var> [<input>...]) + string(`JOIN`_ <glue> <out-var> [<input>...]) + string(`TOLOWER`_ <string> <out-var>) + string(`TOUPPER`_ <string> <out-var>) + string(`LENGTH`_ <string> <out-var>) + string(`SUBSTRING`_ <string> <begin> <length> <out-var>) + string(`STRIP`_ <string> <out-var>) + string(`GENEX_STRIP`_ <string> <out-var>) + string(`REPEAT`_ <string> <count> <out-var>) + + `Comparison`_ + string(`COMPARE`_ <op> <string1> <string2> <out-var>) + + `Hashing`_ + string(`\<HASH\> <HASH_>`_ <out-var> <input>) + + `Generation`_ + string(`ASCII`_ <number>... <out-var>) + string(`HEX`_ <string> <out-var>) + string(`CONFIGURE`_ <string> <out-var> [...]) + string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) + string(`RANDOM`_ [<option>...] <out-var>) + string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) + string(`UUID`_ <out-var> ...) + + `JSON`_ + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + {:ref:`GET <JSON_GET>` | :ref:`TYPE <JSON_TYPE>` | :ref:`LENGTH <JSON_LENGTH>` | :ref:`REMOVE <JSON_REMOVE>`} + <json-string> <member|index> [<member|index> ...]) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + :ref:`MEMBER <JSON_MEMBER>` <json-string> + [<member|index> ...] <index>) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + :ref:`SET <JSON_SET>` <json-string> + <member|index> [<member|index> ...] <value>) + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + :ref:`EQUAL <JSON_EQUAL>` <json-string1> <json-string2>) + +Search and Replace +^^^^^^^^^^^^^^^^^^ + +Search and Replace With Plain Strings +""""""""""""""""""""""""""""""""""""" + +.. _FIND: + +.. code-block:: cmake + + string(FIND <string> <substring> <output_variable> [REVERSE]) + +Return the position where the given ``<substring>`` was found in +the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will +search for the position of the last occurrence of the specified +``<substring>``. If the ``<substring>`` is not found, a position of -1 is +returned. + +The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. +The index stored in ``<output_variable>`` will also be counted in bytes, +so strings containing multi-byte characters may lead to unexpected results. + +.. _REPLACE: + +.. code-block:: cmake + + string(REPLACE <match_string> + <replace_string> <output_variable> + <input> [<input>...]) + +Replace all occurrences of ``<match_string>`` in the ``<input>`` +with ``<replace_string>`` and store the result in the ``<output_variable>``. + +Search and Replace With Regular Expressions +""""""""""""""""""""""""""""""""""""""""""" + +.. _`REGEX MATCH`: + +.. code-block:: cmake + + string(REGEX MATCH <regular_expression> + <output_variable> <input> [<input>...]) + +Match the ``<regular_expression>`` once and store the match in the +``<output_variable>``. +All ``<input>`` arguments are concatenated before matching. +Regular expressions are specified in the subsection just below. + +.. _`REGEX MATCHALL`: + +.. code-block:: cmake + + string(REGEX MATCHALL <regular_expression> + <output_variable> <input> [<input>...]) + +Match the ``<regular_expression>`` as many times as possible and store the +matches in the ``<output_variable>`` as a list. +All ``<input>`` arguments are concatenated before matching. + +.. _`REGEX REPLACE`: + +.. code-block:: cmake + + string(REGEX REPLACE <regular_expression> + <replacement_expression> <output_variable> + <input> [<input>...]) + +Match the ``<regular_expression>`` as many times as possible and substitute +the ``<replacement_expression>`` for the match in the output. +All ``<input>`` arguments are concatenated before matching. + +The ``<replacement_expression>`` may refer to parenthesis-delimited +subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that +two backslashes (``\\1``) are required in CMake code to get a backslash +through argument parsing. + +.. _`Regex Specification`: + +Regex Specification +""""""""""""""""""" + +The following characters have special meaning in regular expressions: + +``^`` + Matches at beginning of input +``$`` + Matches at end of input +``.`` + Matches any single character +``\<char>`` + Matches the single character specified by ``<char>``. Use this to + match special regex characters, e.g. ``\.`` for a literal ``.`` + or ``\\`` for a literal backslash ``\``. Escaping a non-special + character is unnecessary but allowed, e.g. ``\a`` matches ``a``. +``[ ]`` + Matches any character(s) inside the brackets +``[^ ]`` + Matches any character(s) not inside the brackets +``-`` + Inside brackets, specifies an inclusive range between + characters on either side e.g. ``[a-f]`` is ``[abcdef]`` + To match a literal ``-`` using brackets, make it the first + or the last character e.g. ``[+*/-]`` matches basic + mathematical operators. +``*`` + Matches preceding pattern zero or more times +``+`` + Matches preceding pattern one or more times +``?`` + Matches preceding pattern zero or once only +``|`` + Matches a pattern on either side of the ``|`` +``()`` + Saves a matched subexpression, which can be referenced + 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 +expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular +expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. + +CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``, +and ``\\`` may be used to construct literal tabs, carriage returns, +newlines, and backslashes (respectively) to pass in a regex. For example: + +* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches + any single whitespace character. +* The quoted argument ``"[/\\]"`` specifies a regex that matches + a single forward slash ``/`` or backslash ``\``. +* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches + any single "word" character in the C locale. +* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches + the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument + as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This + can alternatively be specified in a :ref:`bracket argument` without + having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``. + +Manipulation +^^^^^^^^^^^^ + +.. _APPEND: + +.. code-block:: cmake + + string(APPEND <string_variable> [<input>...]) + +.. versionadded:: 3.4 + +Append all the ``<input>`` arguments to the string. + +.. _PREPEND: + +.. code-block:: cmake + + string(PREPEND <string_variable> [<input>...]) + +.. versionadded:: 3.10 + +Prepend all the ``<input>`` arguments to the string. + +.. _CONCAT: + +.. code-block:: cmake + + string(CONCAT <output_variable> [<input>...]) + +Concatenate all the ``<input>`` arguments together and store +the result in the named ``<output_variable>``. + +.. _JOIN: + +.. code-block:: cmake + + 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>``. + +To join a list's elements, prefer to use the ``JOIN`` operator +from the :command:`list` command. This allows for the elements to have +special characters like ``;`` in them. + +.. _TOLOWER: + +.. code-block:: cmake + + string(TOLOWER <string> <output_variable>) + +Convert ``<string>`` to lower characters. + +.. _TOUPPER: + +.. code-block:: cmake + + string(TOUPPER <string> <output_variable>) + +Convert ``<string>`` to upper characters. + +.. _LENGTH: + +.. code-block:: cmake + + string(LENGTH <string> <output_variable>) + +Store in an ``<output_variable>`` a given string's length in bytes. +Note that this means if ``<string>`` contains multi-byte characters, the +result stored in ``<output_variable>`` will *not* be the number of characters. + +.. _SUBSTRING: + +.. code-block:: cmake + + string(SUBSTRING <string> <begin> <length> <output_variable>) + +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. + +.. versionchanged:: 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. + +.. _STRIP: + +.. code-block:: cmake + + string(STRIP <string> <output_variable>) + +Store in an ``<output_variable>`` a substring of a given ``<string>`` with +leading and trailing spaces removed. + +.. _GENEX_STRIP: + +.. code-block:: cmake + + 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>``. + +.. _REPEAT: + +.. code-block:: cmake + + string(REPEAT <string> <count> <output_variable>) + +.. versionadded:: 3.15 + +Produce the output string as the input ``<string>`` repeated ``<count>`` times. + +Comparison +^^^^^^^^^^ + +.. _COMPARE: + +.. code-block:: cmake + + string(COMPARE LESS <string1> <string2> <output_variable>) + string(COMPARE GREATER <string1> <string2> <output_variable>) + string(COMPARE EQUAL <string1> <string2> <output_variable>) + string(COMPARE NOTEQUAL <string1> <string2> <output_variable>) + string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) + string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) + +Compare the strings and store true or false in the ``<output_variable>``. + +.. versionadded:: 3.7 + Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. + +.. _`Supported Hash Algorithms`: + +Hashing +^^^^^^^ + +.. _`HASH`: + +.. code-block:: cmake + + string(<HASH> <output_variable> <input>) + +Compute a cryptographic hash of the ``<input>`` string. +The supported ``<HASH>`` algorithm names are: + +``MD5`` + Message-Digest Algorithm 5, RFC 1321. +``SHA1`` + US Secure Hash Algorithm 1, RFC 3174. +``SHA224`` + US Secure Hash Algorithms, RFC 4634. +``SHA256`` + US Secure Hash Algorithms, RFC 4634. +``SHA384`` + US Secure Hash Algorithms, RFC 4634. +``SHA512`` + US Secure Hash Algorithms, RFC 4634. +``SHA3_224`` + Keccak SHA-3. +``SHA3_256`` + Keccak SHA-3. +``SHA3_384`` + Keccak SHA-3. +``SHA3_512`` + Keccak SHA-3. + +.. versionadded:: 3.8 + Added the ``SHA3_*`` hash algorithms. + +Generation +^^^^^^^^^^ + +.. _ASCII: + +.. code-block:: cmake + + string(ASCII <number> [<number> ...] <output_variable>) + +Convert all numbers into corresponding ASCII characters. + +.. _HEX: + +.. code-block:: cmake + + 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. + +.. _CONFIGURE: + +.. code-block:: cmake + + string(CONFIGURE <string> <output_variable> + [@ONLY] [ESCAPE_QUOTES]) + +Transform a ``<string>`` like :command:`configure_file` transforms a file. + +.. _MAKE_C_IDENTIFIER: + +.. code-block:: cmake + + string(MAKE_C_IDENTIFIER <string> <output_variable>) + +Convert each non-alphanumeric character in the input ``<string>`` to an +underscore and store the result in the ``<output_variable>``. If the first +character of the ``<string>`` is a digit, an underscore will also be prepended +to the result. + +.. _RANDOM: + +.. code-block:: cmake + + string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] + [RANDOM_SEED <seed>] <output_variable>) + +Return a random string of given ``<length>`` consisting of +characters from the given ``<alphabet>``. Default length is 5 characters +and default alphabet is all numbers and upper and lower case letters. +If an integer ``RANDOM_SEED`` is given, its value will be used to seed the +random number generator. + +.. _TIMESTAMP: + +.. code-block:: cmake + + string(TIMESTAMP <output_variable> [<format_string>] [UTC]) + +Write a string representation of the current date +and/or time to the ``<output_variable>``. + +If the command is unable to obtain a timestamp, the ``<output_variable>`` +will be set to the empty string ``""``. + +The optional ``UTC`` flag requests the current date/time representation to +be in Coordinated Universal Time (UTC) rather than local time. + +The optional ``<format_string>`` may contain the following format +specifiers: + +``%%`` + .. versionadded:: 3.8 + + A literal percent sign (%). + +``%d`` + The day of the current month (01-31). + +``%H`` + The hour on a 24-hour clock (00-23). + +``%I`` + The hour on a 12-hour clock (01-12). + +``%j`` + The day of the current year (001-366). + +``%m`` + The month of the current year (01-12). + +``%b`` + .. versionadded:: 3.7 + + Abbreviated month name (e.g. Oct). + +``%B`` + .. versionadded:: 3.10 + + Full month name (e.g. October). + +``%M`` + The minute of the current hour (00-59). + +``%s`` + .. versionadded:: 3.6 + + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + +``%S`` + The second of the current minute. 60 represents a leap second. (00-60) + +``%f`` + .. versionadded:: 3.23 + + The microsecond of the current second (000000-999999). + +``%U`` + The week number of the current year (00-53). + +``%V`` + .. versionadded:: 3.22 + + The ISO 8601 week number of the current year (01-53). + +``%w`` + The day of the current week. 0 is Sunday. (0-6) + +``%a`` + .. versionadded:: 3.7 + + Abbreviated weekday name (e.g. Fri). + +``%A`` + .. versionadded:: 3.10 + + Full weekday name (e.g. Friday). + +``%y`` + The last two digits of the current year (00-99). + +``%Y`` + The current year. + +``%z`` + .. versionadded:: 3.26 + + The offset of the time zone from UTC, in hours and minutes, + with format ``+hhmm`` or ``-hhmm``. + +``%Z`` + .. versionadded:: 3.26 + + The time zone name. + +Unknown format specifiers will be ignored and copied to the output +as-is. + +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. + +.. 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. + +.. _UUID: + +.. code-block:: cmake + + 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>``. +The hash algorithm can be either ``MD5`` (Version 3 UUID) or +``SHA1`` (Version 5 UUID). +A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` +where each ``x`` represents a lower case hexadecimal character. +Where required, an uppercase representation can be requested +with the optional ``UPPER`` flag. + +.. _JSON: + +JSON +^^^^ + +.. versionadded:: 3.19 + +Functionality for querying a JSON string. + +.. note:: + In each of the following JSON-related subcommands, if the optional + ``ERROR_VARIABLE`` argument is given, errors will be reported in + ``<error-variable>`` and the ``<out-var>`` will be set to + ``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements + up to the point where the error occurred, or just ``NOTFOUND`` if there + is no relevant path. If an error occurs but the ``ERROR_VARIABLE`` + option is not present, a fatal error message is generated. If no error + occurs, the ``<error-variable>`` will be set to ``NOTFOUND``. + +.. _JSON_GET: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + GET <json-string> <member|index> [<member|index> ...]) + +Get an element from ``<json-string>`` at the location given +by the list of ``<member|index>`` arguments. +Array and object elements will be returned as a JSON string. +Boolean elements will be returned as ``ON`` or ``OFF``. +Null elements will be returned as an empty string. +Number and string types will be returned as strings. + +.. _JSON_TYPE: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + TYPE <json-string> <member|index> [<member|index> ...]) + +Get the type of an element in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. The ``<out-var>`` +will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, +``ARRAY``, or ``OBJECT``. + +.. _JSON_MEMBER: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + MEMBER <json-string> + [<member|index> ...] <index>) + +Get the name of the ``<index>``-th member in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. +Requires an element of object type. + +.. _JSON_LENGTH: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + LENGTH <json-string> [<member|index> ...]) + +Get the length of an element in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. +Requires an element of array or object type. + +.. _JSON_REMOVE: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + REMOVE <json-string> <member|index> [<member|index> ...]) + +Remove an element from ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments. The JSON string +without the removed element will be stored in ``<out-var>``. + +.. _JSON_SET: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-variable>] + SET <json-string> <member|index> [<member|index> ...] <value>) + +Set an element in ``<json-string>`` at the location +given by the list of ``<member|index>`` arguments to ``<value>``. +The contents of ``<value>`` should be valid JSON. + +.. _JSON_EQUAL: +.. code-block:: cmake + + string(JSON <out-var> [ERROR_VARIABLE <error-var>] + EQUAL <json-string1> <json-string2>) + +Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>`` +for equality. The contents of ``<json-string1>`` and ``<json-string2>`` +should be valid JSON. The ``<out-var>`` will be set to a true value if the +JSON objects are considered equal, or a false value otherwise. |