1string 2------ 3 4String operations. 5 6Synopsis 7^^^^^^^^ 8 9.. parsed-literal:: 10 11 `Search and Replace`_ 12 string(`FIND`_ <string> <substring> <out-var> [...]) 13 string(`REPLACE`_ <match-string> <replace-string> <out-var> <input>...) 14 string(`REGEX MATCH`_ <match-regex> <out-var> <input>...) 15 string(`REGEX MATCHALL`_ <match-regex> <out-var> <input>...) 16 string(`REGEX REPLACE`_ <match-regex> <replace-expr> <out-var> <input>...) 17 18 `Manipulation`_ 19 string(`APPEND`_ <string-var> [<input>...]) 20 string(`PREPEND`_ <string-var> [<input>...]) 21 string(`CONCAT`_ <out-var> [<input>...]) 22 string(`JOIN`_ <glue> <out-var> [<input>...]) 23 string(`TOLOWER`_ <string> <out-var>) 24 string(`TOUPPER`_ <string> <out-var>) 25 string(`LENGTH`_ <string> <out-var>) 26 string(`SUBSTRING`_ <string> <begin> <length> <out-var>) 27 string(`STRIP`_ <string> <out-var>) 28 string(`GENEX_STRIP`_ <string> <out-var>) 29 string(`REPEAT`_ <string> <count> <out-var>) 30 31 `Comparison`_ 32 string(`COMPARE`_ <op> <string1> <string2> <out-var>) 33 34 `Hashing`_ 35 string(`\<HASH\> <HASH_>`_ <out-var> <input>) 36 37 `Generation`_ 38 string(`ASCII`_ <number>... <out-var>) 39 string(`HEX`_ <string> <out-var>) 40 string(`CONFIGURE`_ <string> <out-var> [...]) 41 string(`MAKE_C_IDENTIFIER`_ <string> <out-var>) 42 string(`RANDOM`_ [<option>...] <out-var>) 43 string(`TIMESTAMP`_ <out-var> [<format string>] [UTC]) 44 string(`UUID`_ <out-var> ...) 45 46 `JSON`_ 47 string(JSON <out-var> [ERROR_VARIABLE <error-var>] 48 {`GET`_ | `TYPE`_ | :ref:`LENGTH <JSONLENGTH>` | `REMOVE`_} 49 <json-string> <member|index> [<member|index> ...]) 50 string(JSON <out-var> [ERROR_VARIABLE <error-var>] 51 `MEMBER`_ <json-string> 52 [<member|index> ...] <index>) 53 string(JSON <out-var> [ERROR_VARIABLE <error-var>] 54 `SET`_ <json-string> 55 <member|index> [<member|index> ...] <value>) 56 string(JSON <out-var> [ERROR_VARIABLE <error-var>] 57 `EQUAL`_ <json-string1> <json-string2>) 58 59Search and Replace 60^^^^^^^^^^^^^^^^^^ 61 62Search and Replace With Plain Strings 63""""""""""""""""""""""""""""""""""""" 64 65.. _FIND: 66 67.. code-block:: cmake 68 69 string(FIND <string> <substring> <output_variable> [REVERSE]) 70 71Return the position where the given ``<substring>`` was found in 72the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will 73search for the position of the last occurrence of the specified 74``<substring>``. If the ``<substring>`` is not found, a position of -1 is 75returned. 76 77The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. 78The index stored in ``<output_variable>`` will also be counted in bytes, 79so strings containing multi-byte characters may lead to unexpected results. 80 81.. _REPLACE: 82 83.. code-block:: cmake 84 85 string(REPLACE <match_string> 86 <replace_string> <output_variable> 87 <input> [<input>...]) 88 89Replace all occurrences of ``<match_string>`` in the ``<input>`` 90with ``<replace_string>`` and store the result in the ``<output_variable>``. 91 92Search and Replace With Regular Expressions 93""""""""""""""""""""""""""""""""""""""""""" 94 95.. _`REGEX MATCH`: 96 97.. code-block:: cmake 98 99 string(REGEX MATCH <regular_expression> 100 <output_variable> <input> [<input>...]) 101 102Match the ``<regular_expression>`` once and store the match in the 103``<output_variable>``. 104All ``<input>`` arguments are concatenated before matching. 105Regular expressions are specified in the subsection just below. 106 107.. _`REGEX MATCHALL`: 108 109.. code-block:: cmake 110 111 string(REGEX MATCHALL <regular_expression> 112 <output_variable> <input> [<input>...]) 113 114Match the ``<regular_expression>`` as many times as possible and store the 115matches in the ``<output_variable>`` as a list. 116All ``<input>`` arguments are concatenated before matching. 117 118.. _`REGEX REPLACE`: 119 120.. code-block:: cmake 121 122 string(REGEX REPLACE <regular_expression> 123 <replacement_expression> <output_variable> 124 <input> [<input>...]) 125 126Match the ``<regular_expression>`` as many times as possible and substitute 127the ``<replacement_expression>`` for the match in the output. 128All ``<input>`` arguments are concatenated before matching. 129 130The ``<replacement_expression>`` may refer to parenthesis-delimited 131subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that 132two backslashes (``\\1``) are required in CMake code to get a backslash 133through argument parsing. 134 135.. _`Regex Specification`: 136 137Regex Specification 138""""""""""""""""""" 139 140The following characters have special meaning in regular expressions: 141 142``^`` 143 Matches at beginning of input 144``$`` 145 Matches at end of input 146``.`` 147 Matches any single character 148``\<char>`` 149 Matches the single character specified by ``<char>``. Use this to 150 match special regex characters, e.g. ``\.`` for a literal ``.`` 151 or ``\\`` for a literal backslash ``\``. Escaping a non-special 152 character is unnecessary but allowed, e.g. ``\a`` matches ``a``. 153``[ ]`` 154 Matches any character(s) inside the brackets 155``[^ ]`` 156 Matches any character(s) not inside the brackets 157``-`` 158 Inside brackets, specifies an inclusive range between 159 characters on either side e.g. ``[a-f]`` is ``[abcdef]`` 160 To match a literal ``-`` using brackets, make it the first 161 or the last character e.g. ``[+*/-]`` matches basic 162 mathematical operators. 163``*`` 164 Matches preceding pattern zero or more times 165``+`` 166 Matches preceding pattern one or more times 167``?`` 168 Matches preceding pattern zero or once only 169``|`` 170 Matches a pattern on either side of the ``|`` 171``()`` 172 Saves a matched subexpression, which can be referenced 173 in the ``REGEX REPLACE`` operation. 174 175 .. versionadded:: 3.9 176 All regular expression-related commands, including e.g. 177 :command:`if(MATCHES)`, save subgroup matches in the variables 178 :variable:`CMAKE_MATCH_<n>` for ``<n>`` 0..9. 179 180``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|`` 181has lower precedence than concatenation. This means that the regular 182expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular 183expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``. 184 185CMake language :ref:`Escape Sequences` such as ``\t``, ``\r``, ``\n``, 186and ``\\`` may be used to construct literal tabs, carriage returns, 187newlines, and backslashes (respectively) to pass in a regex. For example: 188 189* The quoted argument ``"[ \t\r\n]"`` specifies a regex that matches 190 any single whitespace character. 191* The quoted argument ``"[/\\]"`` specifies a regex that matches 192 a single forward slash ``/`` or backslash ``\``. 193* The quoted argument ``"[A-Za-z0-9_]"`` specifies a regex that matches 194 any single "word" character in the C locale. 195* The quoted argument ``"\\(\\a\\+b\\)"`` specifies a regex that matches 196 the exact string ``(a+b)``. Each ``\\`` is parsed in a quoted argument 197 as just ``\``, so the regex itself is actually ``\(\a\+\b\)``. This 198 can alternatively be specified in a :ref:`bracket argument` without 199 having to escape the backslashes, e.g. ``[[\(\a\+\b\)]]``. 200 201Manipulation 202^^^^^^^^^^^^ 203 204.. _APPEND: 205 206.. code-block:: cmake 207 208 string(APPEND <string_variable> [<input>...]) 209 210.. versionadded:: 3.4 211 212Append all the ``<input>`` arguments to the string. 213 214.. _PREPEND: 215 216.. code-block:: cmake 217 218 string(PREPEND <string_variable> [<input>...]) 219 220.. versionadded:: 3.10 221 222Prepend all the ``<input>`` arguments to the string. 223 224.. _CONCAT: 225 226.. code-block:: cmake 227 228 string(CONCAT <output_variable> [<input>...]) 229 230Concatenate all the ``<input>`` arguments together and store 231the result in the named ``<output_variable>``. 232 233.. _JOIN: 234 235.. code-block:: cmake 236 237 string(JOIN <glue> <output_variable> [<input>...]) 238 239.. versionadded:: 3.12 240 241Join all the ``<input>`` arguments together using the ``<glue>`` 242string and store the result in the named ``<output_variable>``. 243 244To join a list's elements, prefer to use the ``JOIN`` operator 245from the :command:`list` command. This allows for the elements to have 246special characters like ``;`` in them. 247 248.. _TOLOWER: 249 250.. code-block:: cmake 251 252 string(TOLOWER <string> <output_variable>) 253 254Convert ``<string>`` to lower characters. 255 256.. _TOUPPER: 257 258.. code-block:: cmake 259 260 string(TOUPPER <string> <output_variable>) 261 262Convert ``<string>`` to upper characters. 263 264.. _LENGTH: 265 266.. code-block:: cmake 267 268 string(LENGTH <string> <output_variable>) 269 270Store in an ``<output_variable>`` a given string's length in bytes. 271Note that this means if ``<string>`` contains multi-byte characters, the 272result stored in ``<output_variable>`` will *not* be the number of characters. 273 274.. _SUBSTRING: 275 276.. code-block:: cmake 277 278 string(SUBSTRING <string> <begin> <length> <output_variable>) 279 280Store in an ``<output_variable>`` a substring of a given ``<string>``. If 281``<length>`` is ``-1`` the remainder of the string starting at ``<begin>`` 282will be returned. 283 284.. versionchanged:: 3.2 285 If ``<string>`` is shorter than ``<length>`` then the end of the string 286 is used instead. Previous versions of CMake reported an error in this case. 287 288Both ``<begin>`` and ``<length>`` are counted in bytes, so care must 289be exercised if ``<string>`` could contain multi-byte characters. 290 291.. _STRIP: 292 293.. code-block:: cmake 294 295 string(STRIP <string> <output_variable>) 296 297Store in an ``<output_variable>`` a substring of a given ``<string>`` with 298leading and trailing spaces removed. 299 300.. _GENEX_STRIP: 301 302.. code-block:: cmake 303 304 string(GENEX_STRIP <string> <output_variable>) 305 306.. versionadded:: 3.1 307 308Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` 309from the input ``<string>`` and store the result in the ``<output_variable>``. 310 311.. _REPEAT: 312 313.. code-block:: cmake 314 315 string(REPEAT <string> <count> <output_variable>) 316 317.. versionadded:: 3.15 318 319Produce the output string as the input ``<string>`` repeated ``<count>`` times. 320 321Comparison 322^^^^^^^^^^ 323 324.. _COMPARE: 325 326.. code-block:: cmake 327 328 string(COMPARE LESS <string1> <string2> <output_variable>) 329 string(COMPARE GREATER <string1> <string2> <output_variable>) 330 string(COMPARE EQUAL <string1> <string2> <output_variable>) 331 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>) 332 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) 333 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) 334 335Compare the strings and store true or false in the ``<output_variable>``. 336 337.. versionadded:: 3.7 338 Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. 339 340.. _`Supported Hash Algorithms`: 341 342Hashing 343^^^^^^^ 344 345.. _`HASH`: 346 347.. code-block:: cmake 348 349 string(<HASH> <output_variable> <input>) 350 351Compute a cryptographic hash of the ``<input>`` string. 352The supported ``<HASH>`` algorithm names are: 353 354``MD5`` 355 Message-Digest Algorithm 5, RFC 1321. 356``SHA1`` 357 US Secure Hash Algorithm 1, RFC 3174. 358``SHA224`` 359 US Secure Hash Algorithms, RFC 4634. 360``SHA256`` 361 US Secure Hash Algorithms, RFC 4634. 362``SHA384`` 363 US Secure Hash Algorithms, RFC 4634. 364``SHA512`` 365 US Secure Hash Algorithms, RFC 4634. 366``SHA3_224`` 367 Keccak SHA-3. 368``SHA3_256`` 369 Keccak SHA-3. 370``SHA3_384`` 371 Keccak SHA-3. 372``SHA3_512`` 373 Keccak SHA-3. 374 375.. versionadded:: 3.8 376 Added the ``SHA3_*`` hash algorithms. 377 378Generation 379^^^^^^^^^^ 380 381.. _ASCII: 382 383.. code-block:: cmake 384 385 string(ASCII <number> [<number> ...] <output_variable>) 386 387Convert all numbers into corresponding ASCII characters. 388 389.. _HEX: 390 391.. code-block:: cmake 392 393 string(HEX <string> <output_variable>) 394 395.. versionadded:: 3.18 396 397Convert each byte in the input ``<string>`` to its hexadecimal representation 398and store the concatenated hex digits in the ``<output_variable>``. Letters in 399the output (``a`` through ``f``) are in lowercase. 400 401.. _CONFIGURE: 402 403.. code-block:: cmake 404 405 string(CONFIGURE <string> <output_variable> 406 [@ONLY] [ESCAPE_QUOTES]) 407 408Transform a ``<string>`` like :command:`configure_file` transforms a file. 409 410.. _MAKE_C_IDENTIFIER: 411 412.. code-block:: cmake 413 414 string(MAKE_C_IDENTIFIER <string> <output_variable>) 415 416Convert each non-alphanumeric character in the input ``<string>`` to an 417underscore and store the result in the ``<output_variable>``. If the first 418character of the ``<string>`` is a digit, an underscore will also be prepended 419to the result. 420 421.. _RANDOM: 422 423.. code-block:: cmake 424 425 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] 426 [RANDOM_SEED <seed>] <output_variable>) 427 428Return a random string of given ``<length>`` consisting of 429characters from the given ``<alphabet>``. Default length is 5 characters 430and default alphabet is all numbers and upper and lower case letters. 431If an integer ``RANDOM_SEED`` is given, its value will be used to seed the 432random number generator. 433 434.. _TIMESTAMP: 435 436.. code-block:: cmake 437 438 string(TIMESTAMP <output_variable> [<format_string>] [UTC]) 439 440Write a string representation of the current date 441and/or time to the ``<output_variable>``. 442 443If the command is unable to obtain a timestamp, the ``<output_variable>`` 444will be set to the empty string ``""``. 445 446The optional ``UTC`` flag requests the current date/time representation to 447be in Coordinated Universal Time (UTC) rather than local time. 448 449The optional ``<format_string>`` may contain the following format 450specifiers: 451 452``%%`` 453 .. versionadded:: 3.8 454 455 A literal percent sign (%). 456 457``%d`` 458 The day of the current month (01-31). 459 460``%H`` 461 The hour on a 24-hour clock (00-23). 462 463``%I`` 464 The hour on a 12-hour clock (01-12). 465 466``%j`` 467 The day of the current year (001-366). 468 469``%m`` 470 The month of the current year (01-12). 471 472``%b`` 473 .. versionadded:: 3.7 474 475 Abbreviated month name (e.g. Oct). 476 477``%B`` 478 .. versionadded:: 3.10 479 480 Full month name (e.g. October). 481 482``%M`` 483 The minute of the current hour (00-59). 484 485``%s`` 486 .. versionadded:: 3.6 487 488 Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). 489 490``%S`` 491 The second of the current minute. 60 represents a leap second. (00-60) 492 493``%U`` 494 The week number of the current year (00-53). 495 496``%V`` 497 .. versionadded:: 3.22 498 499 The ISO 8601 week number of the current year (01-53). 500 501``%w`` 502 The day of the current week. 0 is Sunday. (0-6) 503 504``%a`` 505 .. versionadded:: 3.7 506 507 Abbreviated weekday name (e.g. Fri). 508 509``%A`` 510 .. versionadded:: 3.10 511 512 Full weekday name (e.g. Friday). 513 514``%y`` 515 The last two digits of the current year (00-99). 516 517``%Y`` 518 The current year. 519 520Unknown format specifiers will be ignored and copied to the output 521as-is. 522 523If no explicit ``<format_string>`` is given, it will default to: 524 525:: 526 527 %Y-%m-%dT%H:%M:%S for local time. 528 %Y-%m-%dT%H:%M:%SZ for UTC. 529 530.. versionadded:: 3.8 531 If the ``SOURCE_DATE_EPOCH`` environment variable is set, 532 its value will be used instead of the current time. 533 See https://reproducible-builds.org/specs/source-date-epoch/ for details. 534 535.. _UUID: 536 537.. code-block:: cmake 538 539 string(UUID <output_variable> NAMESPACE <namespace> NAME <name> 540 TYPE <MD5|SHA1> [UPPER]) 541 542.. versionadded:: 3.1 543 544Create a universally unique identifier (aka GUID) as per RFC4122 545based on the hash of the combined values of ``<namespace>`` 546(which itself has to be a valid UUID) and ``<name>``. 547The hash algorithm can be either ``MD5`` (Version 3 UUID) or 548``SHA1`` (Version 5 UUID). 549A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` 550where each ``x`` represents a lower case hexadecimal character. 551Where required, an uppercase representation can be requested 552with the optional ``UPPER`` flag. 553 554.. _JSON: 555 556JSON 557^^^^ 558 559.. versionadded:: 3.19 560 561Functionality for querying a JSON string. 562 563.. note:: 564 In each of the following JSON-related subcommands, if the optional 565 ``ERROR_VARIABLE`` argument is given, errors will be reported in 566 ``<error-variable>`` and the ``<out-var>`` will be set to 567 ``<member|index>-[<member|index>...]-NOTFOUND`` with the path elements 568 up to the point where the error occurred, or just ``NOTFOUND`` if there 569 is no relevant path. If an error occurs but the ``ERROR_VARIABLE`` 570 option is not present, a fatal error message is generated. If no error 571 occurs, the ``<error-variable>`` will be set to ``NOTFOUND``. 572 573.. _GET: 574.. code-block:: cmake 575 576 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] 577 GET <json-string> <member|index> [<member|index> ...]) 578 579Get an element from ``<json-string>`` at the location given 580by the list of ``<member|index>`` arguments. 581Array and object elements will be returned as a JSON string. 582Boolean elements will be returned as ``ON`` or ``OFF``. 583Null elements will be returned as an empty string. 584Number and string types will be returned as strings. 585 586.. _TYPE: 587.. code-block:: cmake 588 589 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] 590 TYPE <json-string> <member|index> [<member|index> ...]) 591 592Get the type of an element in ``<json-string>`` at the location 593given by the list of ``<member|index>`` arguments. The ``<out-var>`` 594will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, 595``ARRAY``, or ``OBJECT``. 596 597.. _MEMBER: 598.. code-block:: cmake 599 600 string(JSON <out-var> [ERROR_VARIABLE <error-var>] 601 MEMBER <json-string> 602 [<member|index> ...] <index>) 603 604Get the name of the ``<index>``-th member in ``<json-string>`` at the location 605given by the list of ``<member|index>`` arguments. 606Requires an element of object type. 607 608.. _JSONLENGTH: 609.. code-block:: cmake 610 611 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] 612 LENGTH <json-string> <member|index> [<member|index> ...]) 613 614Get the length of an element in ``<json-string>`` at the location 615given by the list of ``<member|index>`` arguments. 616Requires an element of array or object type. 617 618.. _REMOVE: 619.. code-block:: cmake 620 621 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] 622 REMOVE <json-string> <member|index> [<member|index> ...]) 623 624Remove an element from ``<json-string>`` at the location 625given by the list of ``<member|index>`` arguments. The JSON string 626without the removed element will be stored in ``<out-var>``. 627 628.. _SET: 629.. code-block:: cmake 630 631 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] 632 SET <json-string> <member|index> [<member|index> ...] <value>) 633 634Set an element in ``<json-string>`` at the location 635given by the list of ``<member|index>`` arguments to ``<value>``. 636The contents of ``<value>`` should be valid JSON. 637 638.. _EQUAL: 639.. code-block:: cmake 640 641 string(JSON <out-var> [ERROR_VARIABLE <error-var>] 642 EQUAL <json-string1> <json-string2>) 643 644Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>`` 645for equality. The contents of ``<json-string1>`` and ``<json-string2>`` 646should be valid JSON. The ``<out-var>`` will be set to a true value if the 647JSON objects are considered equal, or a false value otherwise. 648