string¶
String operations.
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.\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.New in version 3.9: All regular expression-related commands, including e.g.
if(MATCHES)
, save subgroup 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>...])
New in version 3.4.
Append all the <input>
arguments to the string.
string(PREPEND <string_variable> [<input>...])
New in version 3.10.
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>...])
New in version 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 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.
Changed in version 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.
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>)
New in version 3.1.
Strip any generator expressions
from the input <string>
and store the result in the <output_variable>
.
string(REPEAT <string> <count> <output_variable>)
New in version 3.15.
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>
.
New in version 3.7: Added the LESS_EQUAL
and GREATER_EQUAL
options.
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.
New in version 3.8: Added the SHA3_*
hash algorithms.
Generation¶
string(ASCII <number> [<number> ...] <output_variable>)
Convert all numbers into corresponding ASCII characters.
string(HEX <string> <output_variable>)
New in version 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.
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:
%%
New in version 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
New in version 3.7.
Abbreviated month name (e.g. Oct).
%B
New in version 3.10.
Full month name (e.g. October).
%M
- The minute of the current hour (00-59).
%s
New in version 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
New in version 3.23.
The microsecond of the current second (000000-999999).
%U
- The week number of the current year (00-53).
%V
New in version 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
New in version 3.7.
Abbreviated weekday name (e.g. Fri).
%A
New in version 3.10.
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.
New in version 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.
string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER])
New in version 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¶
New in version 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
.
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> ...])
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.