{"id":112384,"date":"2026-06-04T07:00:00","date_gmt":"2026-06-04T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=112384"},"modified":"2026-06-04T23:27:10","modified_gmt":"2026-06-05T06:27:10","slug":"20260604-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20260604-00\/?p=112384","title":{"rendered":"Rotation revisited: Cycle decomposition in clang’s libcxx"},"content":{"rendered":"

We got distracted by the rotation algorithm in gcc’s libstdc++, but let’s get back to the cycle decomposition algorithm in <\/a> clang’s libcxx<\/a>. <\/a><\/p>\n

The implementation in clang’s libcxx performs the minimum number of swaps, roughly n<\/var>\/2, where n<\/var> is the total number of elements. It does so by viewing the rotation as a permutation and walking through each of the cycles.<\/p>\n

For notational convenience, let a<\/var> be |A| and n<\/var> be |A| + |B| (the total number of elements). The number of cycles is gcd<\/a>(a<\/var>, b<\/var>), and the k<\/var>‘th cycle consists of the elements starting at first<\/code> + k<\/var>, and then stepping to the next element by moving forward another a<\/var> elements, with wraparound, until you return back to the starting point.<\/p>\n

For example, if you have |A| = 4 and |B| = 6, then the cycle that starts at A1 takes 4 steps forward to continues to B1; takes another 4 steps forward to B5; then takes 2 steps forward, wraps around, and then two more steps forward, landing on A3; then takes 4 steps forward to B3; and then takes 4 steps forward and wraps around to A1, which is the starting point.<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
A1<\/td>\nA2<\/td>\nA3<\/td>\nA4<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nB5<\/td>\nB6<\/td>\n<\/tr>\n
\u21b3<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u21b4<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/tr>\n
A1<\/td>\nA2<\/td>\nA3<\/td>\nA4<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nB5<\/td>\nB6<\/td>\n<\/tr>\n
<\/td>\n<\/td>\n<\/td>\n<\/td>\n\u21b3<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u21b4<\/td>\n<\/td>\n<\/tr>\n
A1<\/td>\nA2<\/td>\nA3<\/td>\nA4<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nB5<\/td>\nB6<\/td>\n<\/tr>\n
\u2192<\/td>\n\u2192<\/td>\n\u21b4<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n\u21b3<\/td>\n\u2192<\/td>\n<\/tr>\n
A1<\/td>\nA2<\/td>\nA3<\/td>\nA4<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nB5<\/td>\nB6<\/td>\n<\/tr>\n
<\/td>\n<\/td>\n\u21b3<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u21b4<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/tr>\n
A1<\/td>\nA2<\/td>\nA3<\/td>\nA4<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nB5<\/td>\nB6<\/td>\n<\/tr>\n
\u21b4<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\n\u21b3<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n<\/tr>\n
A1<\/td>\nA2<\/td>\nA3<\/td>\nA4<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nB5<\/td>\nB6<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

There’s another cycle that starts at A2 and continues to B2, B6, A4, B4, then back to A2.<\/p>\n

Now, we’ve been counting swaps, but a single-element rotation is not done as a sequence of swaps, but rather by picking up the first element, sliding all the other elements over, and then putting the original first element at the end. I’ve been informally calling an assignment “half of a swap”, though a swap is really a constructor, two assignments, and a destructor. But let’s stick with the “half a swap” accounting fiction.<\/p>\n

The rotation algorithm goes like this:<\/p>\n

auto a = std::distance(first, mid); \/\/ number of \"A\" elements\r\nauto n = std::distance(first, last); \/\/ total elements\r\nauto g = gcd(a, n); \/\/ number of cycles\r\n\r\nfor (auto k = 0; k < g; ++k) {\r\n    \/\/ Rotate the elements in the cycle starting at k\r\n    auto save = std::move(first[k]);\r\n    auto i, next = k;\r\n    while (i = next, next = (i + a) % n, next != k) {\r\n        first[i] = std::move(first[next]);\r\n    }\r\n    first[i] = std::move(save);\r\n}\r\n<\/pre>\n
For example, if rotating A1, A2, B1, B2, B3, B4, there are two cycles: A1, B1, B3; and A2, B2, B4. The elements within each cycle rotate one position.<\/p>\n\n\n\n\n\n\n\n\n\n
\u2ba3<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2ba7<\/td>\n<\/tr>\n
\u2ba4<\/td>\n<\/td>\n\u2190<\/td>\n<\/td>\n\u2190<\/td>\n<\/td>\n\u2ba0<\/td>\n<\/tr>\n
<\/td>\n<\/tr>\n
\u00a0<\/td>\nA1<\/td>\nA2<\/td>\nB1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\n<\/tr>\n
<\/td>\n<\/tr>\n
\u2ba6<\/td>\n<\/td>\n\u2190<\/td>\n<\/td>\n\u2190<\/td>\n<\/td>\n\u2ba2<\/td>\n<\/tr>\n
\u2ba1<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2192<\/td>\n\u2ba5<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
And when you’re done with all the cycles, you’ve rotated the entire A and B blocks.<\/p>\n\n\n\n
B1<\/td>\nB2<\/td>\nB3<\/td>\nB4<\/td>\nA1<\/td>\nA2<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
This performs n<\/var>\/2 swaps, which is the fewest swaps of all the algorithms we’ve looked at so far. However, it has terrible locality because the elements in the cycle are all spread out.<\/p>\n
Calculating the greated common divisor of two numbers can be done in O<\/var>(log n<\/var>) steps via Euclid’s algorithm.<\/p>\n
int gcd(int a, int b)\r\n{\r\n    do {\r\n        auto r = a % b;\r\n        a = b;\r\n        b = r;\r\n    } while (r);\r\n    return a;\r\n}\r\n<\/pre>\n
 Commenter Brent thought that the cycle decomposition algorithm was obvious<\/a>. Of course, the trick is the step they called “Repeat”. How many times do you repeat?<\/p>\n
The clang libcxx algorithm calculates the number of repeats by taking the gcd. But there’s a trick so we don’t have to calculated it at all. We’ll look at that trick next time.<\/p>\n
Bonus chatter<\/b>: I think it’s interesting that of the three major implementations of the C++ standard library, each one uses a different rotation algorithm when given random-access iterators!<\/p>\n","protected":false},"excerpt":{"rendered":"
Rotating in the minimum number of steps by performing cycle decomposition.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-112384","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Rotating in the minimum number of steps by performing cycle decomposition.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/112384","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=112384"}],"version-history":[{"count":1,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/112384\/revisions"}],"predecessor-version":[{"id":112387,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/112384\/revisions\/112387"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=112384"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=112384"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=112384"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}