string¶
String operations.
Synopsis¶
Search and Replace string(FIND <string> <substring> <out-var> [...]) string(REPLACE <match-string> <replace-string> <out-var> <input>...) Regular Expressions 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(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> ...)
Search and Replace¶
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>
.
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.
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.\a
matchesa
. [ ]
- 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.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 \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 Bracket Argument without having to escape the backslashes, e.g.[[\(\a\+\b\)]]
.
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(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.