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>]
         PARTIAL_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>...])

Заменяет все вхождения <match_string> в <input> на <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), чтобы одна обратная косая черта прошла обработку аргументов.

Описание регулярных выражений

Следующие символы имеют специальное значение в регулярных выражениях:

^

Соответствует началу входной строки

$

Соответствует концу входной строки

.

Соответствует любому одиночному символу

\<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.

Объединяет все аргументы <input> с помощью строки <glue> и сохраняет результат в указанной <output_variable>.

Для объединения элементов списка рекомендуется использовать оператор JOIN команды list(). Это позволяет элементам содержать специальные символы, например ;.

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

Сохраняет в <output_variable> подстроку заданной <string>. Если <length> равен -1, будет возвращена оставшаяся часть строки, начиная с <begin>.

Изменено в версии 3.2: Если <string> выходит за пределы <length>, вместо него используется конец строки. В предыдущих версиях CMake в этом случае сообщала об ошибке.

И <begin>, и <length> отсчитываются в байтах, поэтому следует соблюдать осторожность, если <string> может содержать многобайтовые символы.

string(STRIP <string> <output_variable>)

Сохраняет в <output_variable> подстроку заданной <string>, удалив начальные и конечные пробелы.

string(GENEX_STRIP <string> <output_variable>)

Добавлено в версии 3.1.

Удаляет все generator expressions из входной <string> и сохраняет результат в <output_variable>.

string(REPEAT <string> <count> <output_variable>)

Добавлено в версии 3.15.

Создаёт выходную строку, повторяя входную <string> <count> раз.

string(REGEX QUOTE <out-var> <input>...)

Добавлено в версии 4.2.

Сохраняет в <out-var> регулярное выражение, соответствующее <input>. Все символы, имеющие специальное значение в регулярном выражении, экранируются, чтобы выходную строку можно было использовать как часть регулярного выражения для буквального сопоставления с входной строкой.

Сравнение

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.

Количество секунд с полуночи (UTC) 1 января 1970 года (время 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.

Создаёт универсальный уникальный идентификатор (также называемый GUID) согласно RFC4122 на основе хеша объединённых значений <namespace> (который сам должен быть допустимым UUID) и <name>. Алгоритм хеширования может быть MD5 (UUID версии 3) или SHA1 (UUID версии 5). UUID имеет формат xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, где каждый x обозначает строчную шестнадцатеричную цифру. При необходимости можно запросить представление в верхнем регистре, указав необязательный флаг UPPER.

JSON

Функции для обработки строк JSON.

В следующих подкомандах аргумент <json-string> следует указывать как аргумент в кавычках, чтобы вся строка JSON передавалась как один аргумент, даже если она содержит точки с запятой.

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

Получает элемент из <json-string> в месте, заданном списком аргументов <member|index>. Элементы массивов и объектов возвращаются в виде строки JSON. Булевы элементы возвращаются как ON или OFF. Элементы null возвращаются как пустая строка. Числовые и строковые типы возвращаются в виде строк.

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

Добавлено в версии 4.3.

Получает элемент из <json-string> в месте, заданном списком аргументов <member|index>. Аналогично GET, но не преобразует числовые, строковые, булевы элементы и элементы null.

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

Получает имя <index>-го члена в <json-string> в месте, заданном списком аргументов <member|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> является массивом, <value> можно добавить в конец массива, указав в качестве аргумента <member|index> число, большее или равное длине массива.

string(JSON <out-var> [ERROR_VARIABLE <error-var>] EQUAL <json-string1> <json-string2>)

Сравнивает два объекта JSON, заданные <json-string1> и <json-string2>, на равенство. Содержимое <json-string1> и <json-string2> должно быть допустимым JSON. Для <out-var> устанавливается значение true, если объекты JSON считаются равными, и false в противном случае.

string(JSON <out-var> [ERROR_VARIABLE <error-var>] PARTIAL_EQUAL <json-pattern> <json-actual>)

Добавлено в версии 4.4.

Сравнивает два значения JSON на основе частичного равенства. Первый аргумент (<json-pattern>) рассматривается как шаблон для сопоставления со вторым аргументом (<json-actual>), который рассматривается как полное значение JSON. Содержимое <json-pattern> и <json-actual> должно быть допустимым JSON.

Для <out-var> устанавливается значение true, если <json-pattern> содержится в <json-actual> согласно приведённым ниже правилам, и false в противном случае.

Частичное равенство не является симметричным. В общем случае PARTIAL_EQUAL(A, B) и PARTIAL_EQUAL(B, A) могут давать разные результаты.

Правила сопоставления:

• Скалярные значения (null, число, строка, булево значение) должны совпадать точно.
• Объекты совпадают, если каждый член <json-pattern> существует в <json-actual> и соответствующие значения также рекурсивно совпадают. Дополнительные члены в <json-actual> игнорируются.
• Массивы совпадают, если каждый элемент <json-pattern> рекурсивно совпадает с отдельным элементом <json-actual>. После успешного сопоставления элемента <json-actual> с элементом <json-pattern> этот элемент считается использованным и не может повторно использоваться для сопоставления с последующими элементами. Порядок элементов массива не имеет значения. Дополнительные элементы в <json-actual> игнорируются.

Значения разных типов не совпадают (например, объект не совпадает с массивом, а строка — с числом).

string(JSON <out-var> [ERROR_VARIABLE <error-var>] STRING_ENCODE <string>)

Добавлено в версии 4.3.

Преобразует обычную строку в строку JSON, заключённую в кавычки. Специальные символы внутри строки JSON экранируются надлежащим образом.