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>)

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>)

搜索和替换

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

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

返回在提供的 <string> 中找到给定 <substring> 的位置。如果使用了 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

MATCHALLREPLACE 中允许零长度匹配。以前,它们会触发错误。

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

正则表达式规范

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

^

匹配输入的开头

$

匹配输入的结尾

.

匹配任何单个字符

\<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(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_EQUALGREATER_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> 中。输出中的字母(af)为小写。

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

  • UTC 为 %Y-%m-%dT%H:%M:%SZ

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 中新增。

根据 <namespace>(其本身必须是有效的 UUID)和 <name> 的组合值的哈希,按照 RFC4122 创建一个通用唯一标识符(也称为 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> [<member|index> ...])

<json-string> 中获取由 <member|index> 参数列表给定的位置处的元素。数组和对象元素将作为 JSON 字符串返回。布尔元素将作为 ONOFF 返回。空元素将作为空字符串返回。数字和字符串类型将作为字符串返回。

string(JSON <out-var> [ERROR_VARIABLE <error-variable>] TYPE <json-string> <member|index> [<member|index> ...])

获取 <json-string> 中由 <member|index> 参数列表给定的位置处的元素的类型。<out-var> 将设置为 NULL, NUMBER, STRING, BOOLEAN, ARRAYOBJECT 之一。

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。<out-var> 将设置为 true 值(如果 JSON 对象被认为是相等的),否则设置为 false 值。