================
@@ -0,0 +1,423 @@
+====================
+Clang-Reorder-Fields
+====================
+
+.. contents::
+
+.. toctree::
+ :maxdepth: 1
+
+:program:`clang-reorder-fields` is a refactoring tool to reorder fields in
+C/C++ structs and classes. This tool automatically updates:
+
+- Field declarations in the record definition
+- Constructor initializer lists in C++ classes
+- Aggregate initialization expressions (both C and C++)
+- Designated initializer lists (C++20)
+
+This can be useful for optimizing memory layout, improving cache performance,
+or conforming to coding standards that require specific field orderings.
+
+Example usage
+-------------
+
+Basic struct reordering
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Consider this simple struct in `example.c`:
+
+.. code-block:: c
+
+ struct Foo {
+ const int *x;
+ int y;
+ double z;
+ int w;
+ };
+
+ int main() {
+ const int val = 42;
+ struct Foo foo = { &val, 0, 1.5, 17 };
+ return 0;
+ }
+
+To reorder the fields to `z, w, y, x`, run:
+
+.. code-block:: console
+
+ clang-reorder-fields -record-name Foo -fields-order z,w,y,x example.c --
+
+This will reorder both the struct definition and the initialization:
+
+.. code-block:: c
+
+ struct Foo {
+ double z;
+ int w;
+ int y;
+ const int *x;
+ };
+
+ int main() {
+ const int val = 42;
+ struct Foo foo = { 1.5, 17, 0, &val };
+ return 0;
+ }
+
+Namespaced structs
+~~~~~~~~~~~~~~~~~~
+
+For C++ code with namespaces, use the fully-qualified name:
+
+.. code-block:: c++
+
+ namespace bar {
+ struct Foo {
+ const int *x;
+ int y;
+ double z;
+ int w;
+ };
+ }
+
+.. code-block:: console
+
+ clang-reorder-fields -record-name ::bar::Foo -fields-order z,w,y,x
example.cpp --
+
+For classes defined in the global namespace (without any namespace), you can
+use either the simple class name or prefix it with `::`:
+
+.. code-block:: console
+
+ clang-reorder-fields -record-name Foo -fields-order z,w,y,x example.cpp --
+ # or
+ clang-reorder-fields -record-name ::Foo -fields-order z,w,y,x example.cpp --
+
+C++ constructor initializer lists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tool also reorders constructor initializer lists. Given:
+
+.. code-block:: c++
+
+ class Foo {
+ public:
+ Foo();
+
+ private:
+ int x;
+ const char *s1;
+ const char *s2;
+ double z;
+ };
+
+ Foo::Foo():
+ x(12),
+ s1("abc"),
+ s2("def"),
+ z(3.14)
+ {}
+
+Running:
+
+.. code-block:: console
+
+ clang-reorder-fields -record-name Foo -fields-order s1,x,z,s2 example.cpp --
+
+Will reorder both the field declarations and the constructor initializers:
+
+.. code-block:: c++
+
+ class Foo {
+ public:
+ Foo();
+
+ private:
+ const char *s1;
+ int x;
+ double z;
+ const char *s2;
+ };
+
+ Foo::Foo():
+ s1("abc"),
+ x(12),
+ z(3.14),
+ s2("def")
+ {}
+
+Designated initializers
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For C++20 code using designated initializers:
+
+.. code-block:: c++
+
+ struct Bar {
+ char a;
+ int b;
+ int c;
+ };
+
+ int main() {
+ Bar bar1 = { 'a', 0, 123 };
+ Bar bar2 = { .a = 'a', .b = 0, .c = 123 };
+ return 0;
+ }
+
+.. code-block:: console
+
+ clang-reorder-fields --extra-arg="-std=c++20" -record-name Bar \
+ -fields-order c,a,b example.cpp --
+
+Will produce:
+
+.. code-block:: c++
+
+ struct Bar {
+ int c;
+ char a;
+ int b;
+ };
+
+ int main() {
+ Bar bar1 = { 123, 'a', 0 };
+ Bar bar2 = { .c = 123, .a = 'a', .b = 0 };
+ return 0;
+ }
+
+In-place editing
+~~~~~~~~~~~~~~~~
+
+Use the `-i` flag to modify files in-place:
+
+.. code-block:: console
+
+ clang-reorder-fields -record-name Foo -fields-order z,w,y,x -i example.c --
+
+Limitations and Caveats
+-----------------------
+
+Different access specifiers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tool cannot reorder fields with different access specifiers
+(public/private/protected). All fields being reordered must have the same
----------------
EugeneZelenko wrote:
```suggestion
(``public/private/protected``). All fields being reordered must have the same
```
Please also take care about 80-characters limit.
https://github.com/llvm/llvm-project/pull/178446
_______________________________________________
cfe-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
