summaryrefslogtreecommitdiffstats
path: root/Help/command/string.rst
blob: 4f0c45c2980f6c91dafaa1ff7e63e8c0c1f421d6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
string
------

.. only:: html

   .. contents::

String operations.

Search and Replace
^^^^^^^^^^^^^^^^^^

FIND
""""

::

  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.

REPLACE
"""""""

::

  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.

Regular Expressions
^^^^^^^^^^^^^^^^^^^

REGEX MATCH
"""""""""""

::

  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.

REGEX MATCHALL
""""""""""""""

::

  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.

REGEX REPLACE
"""""""""""""

::

  string(REGEX REPLACE <regular_expression>
         <replace_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 replace expression may refer to paren-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`:

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
``[ ]``
  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. :command:`if(MATCHES)`, in the variables
  :variable:`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``.

Manipulation
^^^^^^^^^^^^

APPEND
""""""

::

  string(APPEND <string variable> [<input>...])

Append all the input arguments to the string.

CONCAT
""""""

::

  string(CONCAT <output variable> [<input>...])

Concatenate all the input arguments together and store
the result in the named output variable.

TOLOWER
"""""""

::

  string(TOLOWER <string1> <output variable>)

Convert string to lower characters.

TOUPPER
"""""""

::

  string(TOUPPER <string1> <output variable>)

Convert string to upper characters.

LENGTH
""""""

::

  string(LENGTH <string> <output variable>)

Store in an output variable a given string's length.

SUBSTRING
"""""""""

::

  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 end of string is used instead.

.. note::
  CMake 3.1 and below reported an error if length pointed past
  the end of string.

STRIP
"""""

::

  string(STRIP <string> <output variable>)

Store in an output variable a substring of a given string with leading and
trailing spaces removed.

GENEX_STRIP
"""""""""""

::

  string(GENEX_STRIP <input string> <output variable>)

Strip any :manual:`generator expressions <cmake-generator-expressions(7)>`
from the ``input string`` and store the result in the ``output variable``.

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.

.. _`Supported Hash Algorithms`:

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

ASCII
"""""

::

  string(ASCII <number> [<number> ...] <output variable>)

Convert all numbers into corresponding ASCII characters.

CONFIGURE
"""""""""

::

  string(CONFIGURE <string1> <output variable>
         [@ONLY] [ESCAPE_QUOTES])

Transform a string like :command:`configure_file` transforms a file.

RANDOM
""""""

::

  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.

TIMESTAMP
"""""""""

::

  string(TIMESTAMP <output variable> [<format string>] [UTC])

Write a string representation of the current date
and/or time to the output variable.

Should the command be 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).
   %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).
   %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.


::

  string(MAKE_C_IDENTIFIER <input string> <output variable>)

Write a string which can be used as an identifier in C.

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

UUID
""""

::

  string(UUID <output variable> NAMESPACE <namespace> NAME <name>
         TYPE <MD5|SHA1> [UPPER])

Create a univerally 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.