string ------ .. only:: html .. contents:: String operations. Search and Replace ^^^^^^^^^^^^^^^^^^ FIND """" :: string(FIND [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 [...]) 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 [...]) Match the regular expression once and store the match in the output variable. All ```` arguments are concatenated before matching. REGEX MATCHALL """""""""""""" :: string(REGEX MATCHALL [...]) Match the regular expression as many times as possible and store the matches in the output variable as a list. All ```` arguments are concatenated before matching. REGEX REPLACE """"""""""""" :: string(REGEX REPLACE [...]) Match the regular expression as many times as possible and substitute the replacement expression for the match in the output. All ```` 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_` for ```` 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 [...]) Append all the input arguments to the string. CONCAT """""" :: string(CONCAT [...]) Concatenate all the input arguments together and store the result in the named output variable. TOLOWER """"""" :: string(TOLOWER ) Convert string to lower characters. TOUPPER """"""" :: string(TOUPPER ) Convert string to upper characters. LENGTH """""" :: string(LENGTH ) Store in an output variable a given string's length. SUBSTRING """"""""" :: string(SUBSTRING ) 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 ) Store in an output variable a substring of a given string with leading and trailing spaces removed. GENEX_STRIP """"""""""" :: string(GENEX_STRIP ) Strip any :manual:`generator expressions ` from the ``input string`` and store the result in the ``output variable``. Comparison ^^^^^^^^^^ :: string(COMPARE LESS ) string(COMPARE GREATER ) string(COMPARE EQUAL ) string(COMPARE NOTEQUAL ) string(COMPARE LESS_EQUAL ) string(COMPARE GREATER_EQUAL ) Compare the strings and store true or false in the output variable. .. _`Supported Hash Algorithms`: Hashing ^^^^^^^ :: string( ) Compute a cryptographic hash of the input string. The supported ```` 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 [ ...] ) Convert all numbers into corresponding ASCII characters. CONFIGURE """"""""" :: string(CONFIGURE [@ONLY] [ESCAPE_QUOTES]) Transform a string like :command:`configure_file` transforms a file. RANDOM """""" :: string(RANDOM [LENGTH ] [ALPHABET ] [RANDOM_SEED ] ) 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 [] [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 ```` 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 ```` 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 ) 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 NAMESPACE NAME TYPE [UPPER]) Create a univerally unique identifier (aka GUID) as per RFC4122 based on the hash of the combined values of ```` (which itself has to be a valid UUID) and ````. 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.