mirror of
https://github.com/reactos/CMake.git
synced 2024-12-13 22:58:41 +00:00
368 lines
8.8 KiB
ReStructuredText
368 lines
8.8 KiB
ReStructuredText
string
|
|
------
|
|
|
|
.. only:: html
|
|
|
|
.. contents::
|
|
|
|
String operations.
|
|
|
|
Search and Replace
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
FIND
|
|
""""
|
|
|
|
::
|
|
|
|
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.
|
|
|
|
REPLACE
|
|
"""""""
|
|
|
|
::
|
|
|
|
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.
|
|
|
|
Regular Expressions
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
REGEX MATCH
|
|
"""""""""""
|
|
|
|
::
|
|
|
|
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.
|
|
|
|
REGEX MATCHALL
|
|
""""""""""""""
|
|
|
|
::
|
|
|
|
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
|
|
"""""""""""""
|
|
|
|
::
|
|
|
|
string(REGEX REPLACE <regular_expression>
|
|
<replace_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 replace expression may refer to paren-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
|
|
``[ ]``
|
|
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. 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.
|
|
|
|
``*``, ``+`` 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``.
|
|
|
|
Manipulation
|
|
^^^^^^^^^^^^
|
|
|
|
APPEND
|
|
""""""
|
|
|
|
::
|
|
|
|
string(APPEND <string variable> [<input>...])
|
|
|
|
Append all the input arguments to the string.
|
|
|
|
CONCAT
|
|
""""""
|
|
|
|
::
|
|
|
|
string(CONCAT <output variable> [<input>...])
|
|
|
|
Concatenate all the input arguments together and store
|
|
the result in the named output variable.
|
|
|
|
TOLOWER
|
|
"""""""
|
|
|
|
::
|
|
|
|
string(TOLOWER <string1> <output variable>)
|
|
|
|
Convert string to lower characters.
|
|
|
|
TOUPPER
|
|
"""""""
|
|
|
|
::
|
|
|
|
string(TOUPPER <string1> <output variable>)
|
|
|
|
Convert string to upper characters.
|
|
|
|
LENGTH
|
|
""""""
|
|
|
|
::
|
|
|
|
string(LENGTH <string> <output variable>)
|
|
|
|
Store in an output variable a given string's length.
|
|
|
|
SUBSTRING
|
|
"""""""""
|
|
|
|
::
|
|
|
|
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.
|
|
If string is shorter than length then end of string is used instead.
|
|
|
|
.. note::
|
|
CMake 3.1 and below reported an error if length pointed past
|
|
the end of string.
|
|
|
|
STRIP
|
|
"""""
|
|
|
|
::
|
|
|
|
string(STRIP <string> <output variable>)
|
|
|
|
Store in an output variable a substring of a given string with leading and
|
|
trailing spaces removed.
|
|
|
|
GENEX_STRIP
|
|
"""""""""""
|
|
|
|
::
|
|
|
|
string(GENEX_STRIP <input string> <output variable>)
|
|
|
|
Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
|
|
from the ``input string`` and store the result in the ``output variable``.
|
|
|
|
Comparison
|
|
^^^^^^^^^^
|
|
|
|
::
|
|
|
|
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.
|
|
|
|
.. _`Supported Hash Algorithms`:
|
|
|
|
Hashing
|
|
^^^^^^^
|
|
|
|
::
|
|
|
|
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.
|
|
|
|
Generation
|
|
^^^^^^^^^^
|
|
|
|
ASCII
|
|
"""""
|
|
|
|
::
|
|
|
|
string(ASCII <number> [<number> ...] <output variable>)
|
|
|
|
Convert all numbers into corresponding ASCII characters.
|
|
|
|
CONFIGURE
|
|
"""""""""
|
|
|
|
::
|
|
|
|
string(CONFIGURE <string1> <output variable>
|
|
[@ONLY] [ESCAPE_QUOTES])
|
|
|
|
Transform a string like :command:`configure_file` transforms a file.
|
|
|
|
RANDOM
|
|
""""""
|
|
|
|
::
|
|
|
|
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
|
|
"""""""""
|
|
|
|
::
|
|
|
|
string(TIMESTAMP <output variable> [<format string>] [UTC])
|
|
|
|
Write a string representation of the current date
|
|
and/or time to the output variable.
|
|
|
|
Should the command be 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:
|
|
|
|
::
|
|
|
|
%% 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 Abbreviated month name (e.g. Oct).
|
|
%M The minute of the current hour (00-59).
|
|
%s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
|
|
%S The second of the current minute.
|
|
60 represents a leap second. (00-60)
|
|
%U The week number of the current year (00-53).
|
|
%w The day of the current week. 0 is Sunday. (0-6)
|
|
%a Abbreviated weekday name (e.g. Fri).
|
|
%y The last two digits of the current year (00-99)
|
|
%Y The current year.
|
|
|
|
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.
|
|
|
|
|
|
::
|
|
|
|
string(MAKE_C_IDENTIFIER <input string> <output variable>)
|
|
|
|
Write a string which can be used as an identifier in C.
|
|
|
|
.. note::
|
|
|
|
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
|
|
""""
|
|
|
|
::
|
|
|
|
string(UUID <output variable> NAMESPACE <namespace> NAME <name>
|
|
TYPE <MD5|SHA1> [UPPER])
|
|
|
|
Create a univerally 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.
|