kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Organize string command docs into sections 

Add section headers and titles for each command signature.  Group
related commands into sections.
This commit is contained in:
Brad King 2015-09-14 10:35:50 -04:00
parent 6dad4c25b0
commit 5f2c47c44c
1 changed files with 227 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

318
Help/command/string.rst
View File

@ -1,102 +1,81 @@
string string
------ ------
.. only:: html
.. contents::
String operations. 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> string(REGEX MATCH <regular_expression>
<output variable> <input> [<input>...]) <output variable> <input> [<input>...])
Match the regular expression once and store the match in the output variable.
REGEX MATCHALL
""""""""""""""
::
string(REGEX MATCHALL <regular_expression> string(REGEX MATCHALL <regular_expression>
<output variable> <input> [<input>...]) <output variable> <input> [<input>...])
Match the regular expression as many times as possible and store the matches
in the output variable as a list.
REGEX REPLACE
"""""""""""""
::
string(REGEX REPLACE <regular_expression> string(REGEX REPLACE <regular_expression>
<replace_expression> <output variable> <replace_expression> <output variable>
<input> [<input>...]) <input> [<input>...])
string(REPLACE <match_string>
<replace_string> <output variable>
<input> [<input>...])
string(APPEND <string variable> [<input>...])
string(CONCAT <output variable> [<input>...])
string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
<output variable> <input>)
string(COMPARE EQUAL <string1> <string2> <output variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
string(COMPARE LESS <string1> <string2> <output variable>)
string(COMPARE GREATER <string1> <string2> <output variable>)
string(ASCII <number> [<number> ...] <output variable>)
string(CONFIGURE <string1> <output variable>
[@ONLY] [ESCAPE_QUOTES])
string(TOUPPER <string1> <output variable>)
string(TOLOWER <string1> <output variable>)
string(LENGTH <string> <output variable>)
string(SUBSTRING <string> <begin> <length> <output variable>)
string(STRIP <string> <output variable>)
string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
[RANDOM_SEED <seed>] <output variable>)
string(FIND <string> <substring> <output variable> [REVERSE])
string(TIMESTAMP <output variable> [<format string>] [UTC])
string(MAKE_C_IDENTIFIER <input string> <output variable>)
string(GENEX_STRIP <input string> <output variable>)
string(UUID <output variable> NAMESPACE <namespace> NAME <name>
TYPE <MD5|SHA1> [UPPER])
``REGEX MATCH`` will match the regular expression once and store the match Match the regular expression as many times as possible and substitute the
in the output variable. replacement expression for the match in the output.
``REGEX MATCHALL`` will match the regular expression as many times as The replace expression may refer to paren-delimited subexpressions of the
possible and store the matches in the output variable as a list. match using ``\1``, ``\2``, ..., ``\9``. Note that two backslashes (``\\1``)
are required in CMake code to get a backslash through argument parsing.
``REGEX REPLACE`` will match the regular expression as many times as Regex Specification
possible and substitute the replacement expression for the match in """""""""""""""""""
the output. 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.
``REPLACE`` will replace all occurrences of ``match_string`` in the input
with ``replace_string`` and store the result in the output.
``APPEND`` will append all the input arguments to the string.
``CONCAT`` will concatenate all the input arguments together and store
the result in the named output variable.
``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, and ``SHA512`` will
compute a cryptographic hash of the input string.
``COMPARE EQUAL``/``COMPARE NOTEQUAL``/``COMPARE LESS/GREATER`` will
compare the strings and store true or false in the output variable.
``ASCII`` will convert all numbers into corresponding ASCII characters.
``CONFIGURE`` will transform a string like :command:`configure_file`
transforms a file.
``TOUPPER``/``TOLOWER`` will convert string to upper/lower characters.
``LENGTH`` will return a given string's length.
``SUBSTRING`` will return 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`` will return a substring of a given string with leading and
trailing spaces removed.
``RANDOM`` will 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.
``FIND`` will 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 following characters have special meaning in regular expressions: The following characters have special meaning in regular expressions:
@ -123,10 +102,159 @@ The following characters have special meaning in regular expressions:
``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|`` ``*``, ``+`` and ``?`` have higher precedence than concatenation. ``|``
has lower precedence than concatenation. This means that the regular has lower precedence than concatenation. This means that the regular
expression "^ab+d$" matches "abbd" but not "ababd", and the regular expression ``^ab+d$`` matches ``abbd`` but not ``ababd``, and the regular
expression "^(ab|cd)$" matches "ab" but not "abd". expression ``^(ab|cd)$`` matches ``ab`` but not ``abd``.
``TIMESTAMP`` will write a string representation of the current date 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 EQUAL <string1> <string2> <output variable>)
string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
string(COMPARE LESS <string1> <string2> <output variable>)
string(COMPARE GREATER <string1> <string2> <output variable>)
Compare the strings and store true or false in the output variable.
Hashing
^^^^^^^
::
string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
<output variable> <input>)
Compute a cryptographic hash of the input string.
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. and/or time to the output variable.
Should the command be unable to obtain a timestamp the output variable Should the command be unable to obtain a timestamp the output variable
@ -163,14 +291,22 @@ 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:%S for local time.
%Y-%m-%dT%H:%M:%SZ for UTC. %Y-%m-%dT%H:%M:%SZ for UTC.
``MAKE_C_IDENTIFIER`` will write a string which can be used as an
identifier in C.
``GENEX_STRIP`` will strip any ::
:manual:`generator expressions <cmake-generator-expressions(7)>` from the
``input string`` and store the result in the ``output variable``.
``UUID`` creates a univerally unique identifier (aka GUID) as per RFC4122 string(MAKE_C_IDENTIFIER <input string> <output variable>)
Write a string which can be used as an identifier in C.
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>`` based on the hash of the combined values of ``<namespace>``
(which itself has to be a valid UUID) and ``<name>``. (which itself has to be a valid UUID) and ``<name>``.
The hash algorithm can be either ``MD5`` (Version 3 UUID) or The hash algorithm can be either ``MD5`` (Version 3 UUID) or