https://cmake.org/cmake/help/latest/command/string.html
Synopsis
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> <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>] {GET | TYPE | LENGTH | REMOVE} <json-string> <member|index> [<member|index> ...]) string(JSON <out-var> [ERROR_VARIABLE <error-var>] MEMBER <json-string> [<member|index> ...] <index>) string(JSON <out-var> [ERROR_VARIABLE <error-var>] SET <json-string> <member|index> [<member|index> ...] <value>) string(JSON <out-var> [ERROR_VARIABLE <error-var>] EQUAL <json-string1> <json-string2>)
Search and Replace
Search and Replace With Plain Strings
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.
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
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.
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.
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
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.amatchesa. [ ]-
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 REPLACEoperation. Additionally it is saved by all regular expression-related commands, including e.g.if(MATCHES), in the variablesCMAKE_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 Escape Sequences such as ,
,
, and \ may be used to construct literal tabs, carriage returns, newlines, and backslashes (respectively) to pass in a regex. For example:
-
The quoted argument
"[ ]"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+). This can alternatively be specified in a Bracket Argument without having to escape the backslashes, e.g.[[(a+)]].
Manipulation
string(APPEND <string_variable> [<input>...])
Append all the <input> arguments to the string.
string(PREPEND <string_variable> [<input>...])
Prepend all the <input> arguments to the string.
string(CONCAT <output_variable> [<input>...])
Concatenate all the <input> arguments together and store the result in the named <output_variable>.
string(JOIN <glue> <output_variable> [<input>...])
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 list() command. This allows for the elements to have special characters like ; in them.
string(TOLOWER <string> <output_variable>)
Convert <string> to lower characters.
string(TOUPPER <string> <output_variable>)
Convert <string> to upper characters.
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.
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 the end of the string is used instead.
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>.
string(STRIP <string> <output_variable>)
Store in an <output_variable> a substring of a given <string> with leading and trailing spaces removed.
string(GENEX_STRIP <string> <output_variable>)
Strip any generator expressions from the input <string> and store the result in the <output_variable>.
string(REPEAT <string> <count> <output_variable>)
Produce the output string as the input <string> repeated <count> times.
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>.
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
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
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.
string(CONFIGURE <string> <output_variable>
[@ONLY] [ESCAPE_QUOTES])
Transform a <string> like configure_file() transforms a file.
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.
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.
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:
%% 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).
%B Full month name (e.g. October).
%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).
%A Full weekday name (e.g. Friday).
%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.
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.
string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER])
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
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.
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.
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.
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.
string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
LENGTH <json-string> <member|index> [<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.
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>.
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.
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.