# 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` matches `a`.
`[ ]`
  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 variables `CMAKE_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.