diff options
| -rw-r--r-- | clang-tools-extra/docs/cpp11-migrate.rst | 239 | ||||
| -rw-r--r-- | clang-tools-extra/docs/index.rst | 4 |
2 files changed, 242 insertions, 1 deletions
diff --git a/clang-tools-extra/docs/cpp11-migrate.rst b/clang-tools-extra/docs/cpp11-migrate.rst new file mode 100644 index 00000000000..55a5d4b99a7 --- /dev/null +++ b/clang-tools-extra/docs/cpp11-migrate.rst @@ -0,0 +1,239 @@ +=========================== +cpp11-migrate User's Manual +=========================== + +:program:`cpp11-migrate` is a standalone tool used to automatically convert +C++98 and C++03 code to use features of the new C++11 standard where +appropriate. + +Basic Usage +=========== + +``cpp11-migrate [options] <source0> [... <sourceN>]`` + +``<source0>...`` specify the paths of files in the CMake source tree, +with the same requirements as other tools built on LibTooling. + +Command Line Options +-------------------- + +.. option:: -fatal-assembler-warnings + + Treat all compiler warnings as errors. + +.. option:: -help + + Displays tool usage instructions and command line options. + +.. option:: -loop-convert + + Makes use of C++11 range-based for loops where possible. + See :ref:`loop-convert-transformation`. + +.. option:: -p=<build-path> + + ``<build-path>`` is a CMake build directory containing a file named + ``compile_commands.json`` which provides compiler options for building + each source file and can be generated by specifying + ``-DCMAKE_EXPORT_COMPILE_COMMANDS`` when running CMake. If ``<build-path>`` + is not provided the ``compile_commands.json`` file is searched for through + all parent directories. + + Alternatively, one can provide compile options to be applied to every + source file after the optional ``--``. + +.. option:: -risk=<risk-level> + + Some transformations may cause a change in semantics. In such cases the + maximum acceptable risk level specified through the ``-risk`` command + line option decides whether or not a transformation is applied. + + Three different risk level options are available: + + ``-risk=safe`` + Perform only safe transformations. + ``-risk=reasonable`` (default) + Enable transformations that may change semantics. + ``-risk=risky`` + Enable transformations that are likely to change semantics. + + See :ref:`transformations` for further details for + risk in individual transformations. + +.. option:: -use-nullptr + + Makes use of the new C++11 keyword ``nullptr`` where possible. + See :ref:`nullptr-convert-transformation`. + +.. option:: -version + + Displays the version information of this tool. + +.. _transformations: + +Transformations +=============== + +.. _loop-convert-transformation: + +Loop Convert +------------ + +Loop convert is a transformation to convert ``for(...; ...; ...)`` loops to use +the new range-based loops in C++11. + +Three kinds of loops can be converted: + +- Loops over statically allocated arrays +- Loops over containers, using iterators +- Loops over array-like containers, using ``operator[]`` and ``at()`` + +Risk +^^^^ + +TODO: Add code examples for which incorrect transformations are performed +when the risk level is set to "Risky" or "Reasonable". + +Risky +""""" + +In loops where the container expression is more complex than just a +reference to a declared expression (a variable, function, enum, etc.), +and some part of it appears elsewhere in the loop, we lower our confidence +in the transformation due to the increased risk of changing semantics. +Transformations for these loops are marked as `risky`, and thus will only +be converted if the acceptable risk level is set to ``-risk=risky``. + +.. code-block:: c++ + + int arr[10][20]; + int l = 5; + + for (int j = 0; j < 20; ++j) + int k = arr[l][j] + l; // using l outside arr[l] is considered risky + + for (int i = 0; i < obj.getVector().size(); ++i) + obj.foo(10); // using 'obj' is considered risky + +Reasonable (Default) +"""""""""""""""""""" + +If a loop calls ``.end()`` or ``.size()`` after each iteration, the +transformation for that loop is marked as `reasonable`, and thus will +be converted if the acceptable risk level is set to ``-risk=reasonable`` +(default) or higher. + +.. code-block:: c++ + + // using size() is considered reasonable + for (int i = 0; i < container.size(); ++i) + cout << container[i]; + +Safe +"""" + +Any other loops that do not match the above criteria to be marked as +`risky` or `reasonable` are marked `safe`, and thus will be converted +if the acceptable risk level is set to ``-risk=safe`` or higher. + +.. code-block:: c++ + + int arr[] = {1,2,3}; + + for (int i = 0; i < 3; ++i) + cout << arr[i]; + +Example +^^^^^^^ + +Original +"""""""" + +.. code-block:: c++ + + const int N = 5; + int arr[] = {1,2,3,4,5}; + vector<int> v; + v.push_back(1); + v.push_back(2); + v.push_back(3); + + // safe transform + for (int i = 0; i < N; ++i) + cout << arr[i]; + + // reasonable transform + for (vector<int>::iterator it = v.begin(); it != v.end(); ++it) + cout << *it; + + // reasonable transform + for (int i = 0; i < v.size(); ++i) + cout << v[i]; + + +After transformation +"""""""""""""""""""" +With risk level set to ``-risk=reasonable`` (default). + +.. code-block:: c++ + + const int N = 5; + int arr[] = {1,2,3,4,5}; + vector<int> v; + v.push_back(1); + v.push_back(2); + v.push_back(3); + + // safe transform + for (auto & elem : arr) + cout << elem; + + // reasonable transform + for (auto & elem : v) + cout << elem; + + // reasonable transform + for (auto & elem : v) + cout << elem; + +.. _nullptr-convert-transformation: + +Nullptr Convert +--------------- + +Nullptr convert is a transformation to convert the usage of null pointer +constants (eg. ``NULL``, ``0``) to use the new C++11 ``nullptr`` keyword. + +Example +^^^^^^^ + +Original +"""""""" + +.. code-block:: c++ + + void assignment() { + char *a = NULL; + char *b = 0; + char c = 0; + } + + int *ret_ptr() { + return 0; + } + + +After transformation +"""""""""""""""""""" + +.. code-block:: c++ + + void assignment() { + char *a = nullptr; + char *b = nullptr; + char c = 0; + } + + int *ret_ptr() { + return nullptr; + } diff --git a/clang-tools-extra/docs/index.rst b/clang-tools-extra/docs/index.rst index b45bb88cb46..d39f54c3e3a 100644 --- a/clang-tools-extra/docs/index.rst +++ b/clang-tools-extra/docs/index.rst @@ -8,7 +8,9 @@ Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + cpp11-migrate |
