forked from OSchip/llvm-project
Splitting cpp11-migrate transform docs into sub-pages
Each transform belongs in its own sub-page now. Minor refactoring to reflect new heading levels. llvm-svn: 176757
This commit is contained in:
Edwin Vane
parent
5497d1a55c
commit
e4e7c24efc
|
|
@ -0,0 +1,120 @@
|
|||
.. index:: Loop Convert Transform
|
||||
|
||||
======================
|
||||
Loop Convert Transform
|
||||
======================
|
||||
|
||||
The Loop Convert Transform is a transformation to convert ``for(...; ...;
|
||||
...)`` loops to use the new range-based loops in C++11. The transform is enabled
|
||||
with the :option:`-loop-convert` option of :program:`cpp11-migrate`.
|
||||
|
||||
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;
|
||||
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
.. index:: Loop Convert Transform
|
||||
.. index:: Use-Auto Transform
|
||||
|
||||
==================
|
||||
Use-Auto Transform
|
||||
|
|
|
|||
|
|
@ -0,0 +1,40 @@
|
|||
.. index:: Use-Nullptr Transform
|
||||
|
||||
=====================
|
||||
Use-Nullptr Transform
|
||||
=====================
|
||||
|
||||
The Use-Nullptr Transform is a transformation to convert the usage of null
|
||||
pointer constants (eg. ``NULL``, ``0``) to use the new C++11 ``nullptr``
|
||||
keyword. The transform is enabled with the :option:`-use-nullptr` option of
|
||||
:program:`cpp11-migrate`.
|
||||
|
||||
Example
|
||||
=======
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
void assignment() {
|
||||
char *a = NULL;
|
||||
char *b = 0;
|
||||
char c = 0;
|
||||
}
|
||||
|
||||
int *ret_ptr() {
|
||||
return 0;
|
||||
}
|
||||
|
||||
|
||||
transforms to:
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
void assignment() {
|
||||
char *a = nullptr;
|
||||
char *b = nullptr;
|
||||
char c = 0;
|
||||
}
|
||||
|
||||
int *ret_ptr() {
|
||||
return nullptr;
|
||||
}
|
||||
|
|
@ -1,3 +1,5 @@
|
|||
.. index:: cpp11-migrate
|
||||
|
||||
===========================
|
||||
cpp11-migrate User's Manual
|
||||
===========================
|
||||
|
|
@ -6,6 +8,8 @@ cpp11-migrate User's Manual
|
|||
:hidden:
|
||||
|
||||
UseAutoTransform
|
||||
UseNullptrTransform
|
||||
LoopConvertTransform
|
||||
|
||||
: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
|
||||
|
|
@ -32,8 +36,13 @@ Command Line Options
|
|||
|
||||
.. option:: -loop-convert
|
||||
|
||||
Makes use of C++11 range-based for loops where possible.
|
||||
See :ref:`loop-convert-transformation`.
|
||||
Makes use of C++11 range-based for loops where possible. See
|
||||
:doc:`LoopConvertTransform`.
|
||||
|
||||
.. option:: -use-nullptr
|
||||
|
||||
Makes use of the new C++11 keyword ``nullptr`` where possible.
|
||||
See :doc:`UseNullptrTransform`.
|
||||
|
||||
.. option:: -use-auto
|
||||
|
||||
|
|
@ -67,183 +76,21 @@ Command Line Options
|
|||
``-risk=risky``
|
||||
Enable transformations that are likely to change semantics.
|
||||
|
||||
See :ref:`transformations` for further details for
|
||||
risk in individual transformations.
|
||||
The meaning of risk is handled differently for each transform. See
|
||||
:ref:`transform documentation <transforms>` for details.
|
||||
|
||||
.. 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:
|
||||
.. _transforms:
|
||||
|
||||
Transformations
|
||||
===============
|
||||
|
||||
.. _loop-convert-transformation:
|
||||
* :doc:`LoopConvertTransform`
|
||||
|
||||
Loop Convert
|
||||
------------
|
||||
* :doc:`UseNullptrTransform`
|
||||
|
||||
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;
|
||||
}
|
||||
* :doc:`UseAutoTransform`
|
||||
|
|
|
|||
Loading…
Reference in New Issue