[clang-tools-extra] r176757 - Splitting cpp11-migrate transform docs into sub-pages
Edwin Vane
edwin.vane at intel.com
Fri Mar 8 19:33:50 PST 2013
Author: revane
Date: Fri Mar 8 21:33:50 2013
New Revision: 176757
URL: http://llvm.org/viewvc/llvm-project?rev=176757&view=rev
Log:
Splitting cpp11-migrate transform docs into sub-pages
Each transform belongs in its own sub-page now. Minor refactoring to reflect
new heading levels.
Added:
clang-tools-extra/trunk/docs/LoopConvertTransform.rst
clang-tools-extra/trunk/docs/UseNullptrTransform.rst
Modified:
clang-tools-extra/trunk/docs/UseAutoTransform.rst
clang-tools-extra/trunk/docs/cpp11-migrate.rst
Added: clang-tools-extra/trunk/docs/LoopConvertTransform.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/LoopConvertTransform.rst?rev=176757&view=auto
==============================================================================
--- clang-tools-extra/trunk/docs/LoopConvertTransform.rst (added)
+++ clang-tools-extra/trunk/docs/LoopConvertTransform.rst Fri Mar 8 21:33:50 2013
@@ -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;
+
Modified: clang-tools-extra/trunk/docs/UseAutoTransform.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/UseAutoTransform.rst?rev=176757&r1=176756&r2=176757&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/UseAutoTransform.rst (original)
+++ clang-tools-extra/trunk/docs/UseAutoTransform.rst Fri Mar 8 21:33:50 2013
@@ -1,4 +1,4 @@
-.. index:: Loop Convert Transform
+.. index:: Use-Auto Transform
==================
Use-Auto Transform
Added: clang-tools-extra/trunk/docs/UseNullptrTransform.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/UseNullptrTransform.rst?rev=176757&view=auto
==============================================================================
--- clang-tools-extra/trunk/docs/UseNullptrTransform.rst (added)
+++ clang-tools-extra/trunk/docs/UseNullptrTransform.rst Fri Mar 8 21:33:50 2013
@@ -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;
+ }
Modified: clang-tools-extra/trunk/docs/cpp11-migrate.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/cpp11-migrate.rst?rev=176757&r1=176756&r2=176757&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/cpp11-migrate.rst (original)
+++ clang-tools-extra/trunk/docs/cpp11-migrate.rst Fri Mar 8 21:33:50 2013
@@ -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.
-
-.. option:: -use-nullptr
+ The meaning of risk is handled differently for each transform. See
+ :ref:`transform documentation <transforms>` for details.
- 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:
-
-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++
+* :doc:`LoopConvertTransform`
- void assignment() {
- char *a = nullptr;
- char *b = nullptr;
- char c = 0;
- }
+* :doc:`UseNullptrTransform`
- int *ret_ptr() {
- return nullptr;
- }
+* :doc:`UseAutoTransform`
More information about the cfe-commits
mailing list