string¶

字符串操作。

概要¶

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>)
  string(REGEX QUOTE <out-var> <input>...)

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 | GET_RAW | TYPE | LENGTH}
         <json-string> [<member|index> ...])
  string(JSON <out-var> [ERROR_VARIABLE <error-var>]
         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>)
  string(JSON <out-var> [ERROR_VARIABLE <error-var>]
         STRING_ENCODE <string>)

搜索和替换¶

使用纯字符串进行搜索和替换¶

string(FIND <string> <substring> <output_variable> [REVERSE])¶

返回给定 <substring> 在提供的 <string> 中被找到的位置。如果使用了 REVERSE 标志，该命令将搜索指定 <substring> 的最后一个出现位置。如果未找到 <substring>，则返回位置 -1。

string(FIND) 子命令将所有字符串视为仅 ASCII 字符。存储在 <output_variable> 中的索引也将以字节为单位计数，因此包含多字节字符的字符串可能会导致意外结果。

string(REPLACE <match_string> <replace_string> <output_variable> <input> [<input>...])¶: 将 <input> 中所有出现的 <match_string> 替换为 <replace_string>，并将结果存储在 <output_variable> 中。

使用正则表达式进行搜索和替换¶

string(REGEX MATCH <regular_expression> <output_variable> <input> [<input>...])¶: 匹配 <regular_expression> 一次，并将匹配项存储在 <output_variable> 中。在匹配之前，所有 <input> 参数都会被连接起来。正则表达式在下面的小节中指定。

string(REGEX MATCHALL <regular_expression> <output_variable> <input> [<input>...])¶: 尽可能多次匹配 <regular_expression>，并将匹配项作为列表存储在 <output_variable> 中。在匹配之前，所有 <input> 参数都会被连接起来。

string(REGEX REPLACE <regular_expression> <replacement_expression> <output_variable> <input> [<input>...])¶

尽可能多次匹配 <regular_expression>，并在输出中用 <replacement_expression> 替换匹配项。在匹配之前，所有 <input> 参数都会被连接起来。

<replacement_expression> 可以使用 \1、\2、...、\9 引用匹配项中用括号分隔的子表达式。请注意，在 CMake 代码中需要两个反斜杠 (\\1) 才能通过参数解析获得反斜杠。

版本 4.1 中更改：^ 锚点现在仅匹配输入字符串的开头，而不是每个重复搜索的开头。请参阅策略 CMP0186。

在 MATCHALL 和 REPLACE 中允许零长度匹配。以前，它们会触发错误。

替换表达式可以包含对未匹配任何内容的子表达式的引用。以前，此类引用会触发错误。

正则表达式规范¶

以下字符在正则表达式中具有特殊含义

^: 匹配输入开头
$: 匹配输入结尾
.: 匹配任何单个字符
<char>: 匹配指定的单个字符 <char>。使用此方法匹配特殊正则表达式字符，例如 \. 以匹配字面量 . 或 \\ 以匹配字面量反斜杠 \。逃避非特殊字符是不必要的，但允许，例如 \a 匹配 a。
[ ]: 匹配方括号内的任何字符。要匹配字面量 ]，使其成为第一个字符，例如 []ab]。
[^ ]: 匹配不在方括号内的任何字符。要不匹配字面量 ]，使其成为第一个字符，例如 [^]ab]。
-: 在方括号内，指定两侧字符之间的包含范围，例如 [a-f] 是 [abcdef]。要在方括号中匹配字面量 -，使其成为第一个或最后一个字符，例如 [+*/-] 匹配基本的数学运算符。
*: 匹配前模式零次或多次
+: 匹配前模式一次或多次
?: 匹配前模式零次或一次
|: 匹配 | 两侧的模式
(): 保存匹配的子表达式，可以在 REGEX REPLACE 操作中引用它。

版本 3.9 中添加：所有与正则表达式相关的命令，包括例如 if(MATCHES)，将子组匹配项保存到变量 CMAKE_MATCH_<n>，其中 <n> 为 0..9。

*、+ 和 ? 的优先级高于连接。 | 的优先级低于连接。这意味着正则表达式 ^ab+d$ 匹配 abbd 但不匹配 ababd，正则表达式 ^(ab|cd)$ 匹配 ab 但不匹配 abd。

CMake 语言转义序列，例如 \t、\r、\n 和 \\ 可用于构造字面量制表符、回车符、换行符和反斜杠（分别）以传递给正则表达式。例如

带引号的参数 "[ \t\r\n]" 指定一个匹配任何单个空白字符的正则表达式。
带引号的参数 "[/\\]" 指定一个匹配单个正斜杠 / 或反斜杠 \ 的正则表达式。
带引号的参数 "[A-Za-z0-9_]" 指定一个匹配 C 语言环境中的任何单个“单词”字符的正则表达式。
引用的参数 "\$\\a\\+b\$" 指定了一个正则表达式，它匹配确切的字符串 (a+b)。在引用的参数中，每个 \\ 都会被解析为 \，因此正则表达式本身实际上是 $\a\+\b$。这也可以在方括号参数中指定，而无需转义反斜杠，例如 [[$\a\+\b$]]。

操作¶

string(APPEND <string_variable> [<input>...])¶: 3.4 版本新增。

将所有 <input> 参数附加到字符串。

string(PREPEND <string_variable> [<input>...])¶: 3.10 版本新增。

将所有 <input> 参数添加到字符串的前面。

string(CONCAT <output_variable> [<input>...])¶: 将所有 <input> 参数连接在一起，并将结果存储在指定的 <output_variable> 中。

string(JOIN <glue> <output_variable> [<input>...])¶

3.12 版本新增。

使用 <glue> 字符串将所有 <input> 参数连接在一起，并将结果存储在指定的 <output_variable> 中。

要连接列表的元素，最好使用 list() 命令中的 JOIN 操作符。这允许元素具有特殊字符，例如 ;。

string(TOLOWER <string> <output_variable>)¶: 将 <string> 转换为小写字符。

string(TOUPPER <string> <output_variable>)¶: 将 <string> 转换为大写字符。

string(LENGTH <string> <output_variable>)¶: 将给定字符串的长度（以字节为单位）存储在 <output_variable> 中。请注意，这意味着如果 <string> 包含多字节字符，则存储在 <output_variable> 中的结果将不是字符数。

string(SUBSTRING <string> <begin> <length> <output_variable>)¶

将给定 <string> 的子字符串存储在 <output_variable> 中。如果 <length> 为 -1，则将从 <begin> 开始的字符串的其余部分返回。

3.2 版本更改：如果 <string> 短于 <length>，则将使用字符串的末尾。CMake 的早期版本在此情况下报告错误。

<begin> 和 <length> 都是以字节为单位计算的，因此如果 <string> 可能包含多字节字符，则必须小心。

string(STRIP <string> <output_variable>)¶: 将给定 <string> 的子字符串存储在 <output_variable> 中，并删除前导和尾随空格。

string(GENEX_STRIP <string> <output_variable>)¶: 版本 3.1 中新增。

从输入 <string> 中删除任何 生成器表达式，并将结果存储在 <output_variable> 中。

string(REPEAT <string> <count> <output_variable>)¶: 版本 3.15 新增。

将输出字符串生成为输入 <string> 重复 <count> 次。

string(REGEX QUOTE <out-var> <input>...)¶: 版本 4.2 中添加。

将正则表达式匹配 <input> 存储在 <out-var> 中。转义所有在正则表达式中具有特殊含义的字符，以便输出字符串可以作为正则表达式的一部分用于字面匹配输入。

比较¶

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>)¶: 比较字符串并将 true 或 false 存储在 <output_variable> 中。

在 3.7 版本中添加：添加了 LESS_EQUAL 和 GREATER_EQUAL 选项。

哈希¶

string(<HASH> <output_variable> <input>)¶

计算 <input> 字符串的密码学哈希值。支持的 <HASH> 算法名称是

MD5: 消息摘要算法 5，RFC 1321。
SHA1: 美国安全哈希算法 1，RFC 3174。
SHA224: 美国安全哈希算法，RFC 4634。
SHA256: 美国安全哈希算法，RFC 4634。
SHA384: 美国安全哈希算法，RFC 4634。
SHA512: 美国安全哈希算法，RFC 4634。
SHA3_224: Keccak SHA-3。
SHA3_256: Keccak SHA-3。
SHA3_384: Keccak SHA-3。
SHA3_512: Keccak SHA-3。

在 3.8 版本中添加：添加了 SHA3_* 哈希算法。

生成¶

string(ASCII <number> [<number> ...] <output_variable>)¶: 将所有数字转换为相应的 ASCII 字符。

string(HEX <string> <output_variable>)¶: 在 3.18 版本中新增。

将输入 <string> 中的每个字节转换为其十六进制表示形式，并将连接后的十六进制数字存储在 <output_variable> 中。输出中的字母（a 到 f）均为小写。

string(CONFIGURE <string> <output_variable> [@ONLY] [ESCAPE_QUOTES])¶: 转换一个 <string>，就像 configure_file() 转换一个文件一样。

string(MAKE_C_IDENTIFIER <string> <output_variable>)¶: 将输入 <string> 中的每个非字母数字字符转换为下划线，并将结果存储在 <output_variable> 中。如果 <string> 的第一个字符是数字，则结果前面也会添加一个下划线。

string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RANDOM_SEED <seed>] <output_variable>)¶: 返回一个给定 <length> 的随机字符串，该字符串由给定的 <alphabet> 中的字符组成。默认长度为 5 个字符，默认字母表包含所有数字以及大写和小写字母。如果给定了整数 RANDOM_SEED，则其值将用于初始化随机数生成器。

string(TIMESTAMP <output_variable> [<format_string>] [UTC])¶

将当前日期和/或时间的字符串表示形式写入 <output_variable>。

如果命令无法获取时间戳，则 <output_variable> 将设置为空字符串 ""。

可选的 UTC 标志请求当前日期/时间表示形式以协调世界时 (UTC) 而不是本地时间。

可选的 <format_string> 可以包含以下格式说明符

%%: 版本 3.8 新增。

文字百分号 (%)。
%d: 当前月份的日期 (01-31)。
%H: 24 小时制的小时数 (00-23)。
%I: 12 小时制的小时数 (01-12)。
%j: 当前年份的第几天 (001-366)。
%m: 当前年份的月份 (01-12)。
%b: 3.7 版本中新增。

缩写的月份名称（例如 Oct）。
%B: 3.10 版本新增。

完整的月份名称（例如 October）。
%M: 当前小时的分钟数 (00-59)。
%s: 3.6 版本新增。

自 1970 年 1 月 1 日午夜以来经过的秒数 (UTC)（UNIX 时间）。
%S: 当前分钟的秒数。60 表示闰秒。(00-60)
%f: 在版本 3.23 中添加。

当前秒的微秒数 (000000-999999)。
%U: 当前年份的周数 (00-53)。
%V: 3.22 版本新增。

当前年份的 ISO 8601 周数 (01-53)。
%w: 当前星期几。0 是星期日。(0-6)
%a: 3.7 版本中新增。

缩写的星期几名称（例如 Fri）。
%A: 3.10 版本新增。

完整的星期几名称（例如 Friday）。
%y: 当前年份的最后两位数字 (00-99)。
%Y: 当前年份。
%z: 3.26 版新增。

从 UTC 的时区偏移量，以小时和分钟为单位，格式为 +hhmm 或 -hhmm。
%Z: 3.26 版新增。

时区名称。

未知的格式说明符将被忽略并按原样复制到输出中。

如果未提供显式的 <format_string>，则默认值为

%Y-%m-%dT%H:%M:%S 用于本地时间。
%Y-%m-%dT%H:%M:%SZ 用于 UTC。

在 3.8 版本中添加：如果设置了环境变量 SOURCE_DATE_EPOCH，则其值将代替当前时间。有关详细信息，请参阅 https://reproducible-builds.org/specs/source-date-epoch/。

string(UUID <output_variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER])¶: 版本 3.1 中新增。

根据 RFC4122 中结合 <namespace>（本身必须是有效的 UUID）和 <name> 的哈希值创建通用唯一标识符（又称 GUID）。哈希算法可以是 MD5（版本 3 UUID）或 SHA1（版本 5 UUID）。UUID 的格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx，其中每个 x 代表一个小写十六进制字符。如果需要，可以使用可选的 UPPER 标志请求大写表示形式。

JSON¶

3.19 版本新增。

用于查询 JSON 字符串的功能。

注意

在以下每个与 JSON 相关的子命令中，如果给出了可选的 ERROR_VARIABLE 参数，错误将报告在 <error-variable> 中，并且 <out-var> 将被设置为 <member|index>-[<member|index>...]-NOTFOUND，其中包含发生错误点的路径元素，或者如果不存在相关路径，则仅设置为 NOTFOUND。如果发生错误但未提供 ERROR_VARIABLE 选项，则会生成致命错误消息。如果没有发生错误，<error-variable> 将被设置为 NOTFOUND。

在以下子命令中，<json-string> 参数应写为带引号的参数，以确保整个 JSON 字符串作为单个参数传递，即使它包含分号也是如此。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] GET <json-string> [<member|index> ...])¶: 从 <json-string> 获取位于由 <member|index> 参数列表给出的位置的元素。数组和对象元素将作为 JSON 字符串返回。布尔元素将作为 ON 或 OFF 返回。空元素将作为空字符串返回。数字和字符串类型将作为字符串返回。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] GET_RAW <json-string> [<member|index> ...])¶: Added in version 4.3.

从 <json-string> 获取位于由 <member|index> 参数列表给出的位置的元素。与 GET 类似，但不转换数字、字符串、布尔值或空元素。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] TYPE <json-string> [<member|index> ...])¶: 获取 <json-string> 中位于由 <member|index> 参数列表给出的位置的元素的类型。<out-var> 将被设置为 NULL、NUMBER、STRING、BOOLEAN、ARRAY 或 OBJECT 中的一个。

string(JSON <out-var> [ERROR_VARIABLE <error-var>] MEMBER <json-string> [<member|index> ...] <index>)¶: 获取 <json-string> 中位于由 <member|index> 参数列表给出的位置的第 <index> 个成员的名称。需要对象类型的元素。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] LENGTH <json-string> [<member|index> ...])¶: 获取 <json-string> 中位于由 <member|index> 参数列表给出的位置的元素的长度。需要数组或对象类型的元素。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] REMOVE <json-string> <member|index> [<member|index> ...])¶: 从 <json-string> 中删除位于由 <member|index> 参数列表给出的位置的元素。不包含已删除元素的 JSON 字符串将存储在 <out-var> 中。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] SET <json-string> <member|index> [<member|index> ...] <value>)¶: 在 <json-string> 中，根据 <member|index> 参数指定的列表位置，将元素设置为 <value>。 <value> 的内容应该是有效的 JSON。如果 <json-string> 是一个数组，可以使用大于或等于数组长度的数字作为 <member|index> 参数，将 <value> 追加到数组的末尾。

string(JSON <out-var> ［ERROR_VARIABLE <error-var>］ EQUAL <json-string1> <json-string2>)¶: 比较由 <json-string1> 和 <json-string2> 给定的两个 JSON 对象是否相等。 <json-string1> 和 <json-string2> 的内容应该是有效的 JSON。如果 JSON 对象被认为是相等的，则 <out-var> 将被设置为一个真值；否则，将设置为一个假值。

string(JSON <out-var> ［ERROR_VARIABLE <error-var>］ STRING_ENCODE <string>)¶: Added in version 4.3.

将原始字符串转换为用引号括起来的 JSON 字符串。JSON 字符串内部的特殊字符将被正确转义。