[clang-tidy] modernize: Find usage of random_shuffle and replace it with shuffle.

[madsravn]

Summary

random_shuffle was deprecated by C++14 and will be removed by C++17. This check will find and replace usage of random_shuffle with its modern counterpart (shuffle).

[Eugene.Zelenko]

docs/ReleaseNotes.rst

78 ↗

(On Diff #89071)

Please add std:: and enclose random_shuffle in ``.

docs/clang-tidy/checks/modernize-replace-random-shuffle.rst

6 ↗

(On Diff #89071)

I think std:: should be added.

[xazax.hun]

Nice check! Thank you for working on this!

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

30 ↗

(On Diff #89071)

Maybe it would be worth to reflow this literal.

70 ↗

(On Diff #89071)

What about accessing the buffer of the source file instead of pretty printing?

81 ↗

(On Diff #89071)

Wouldn't just using the original source range of the argument work?
What about preserving the comments next to the arguments?

101 ↗

(On Diff #89071)

You do not want to do fixits for code that is the result of macro expansions.

docs/clang-tidy/checks/modernize-replace-random-shuffle.rst

24 ↗

(On Diff #89071)

Isn't it a performance problem in general to always reinitialize a random engine? Maybe the documentation should contain a notice that in case of performance critical code the user might want to factor the last parameter out somewhere.

test/clang-tidy/modernize-replace-random-shuffle.cpp

50 ↗

(On Diff #89071)

This check-fix might match the previous fix instead of this one. You might want to make the fixes unique, e.g.: with a comment after a line. Note that it is also worth to test that line ending comments are preserved.

Also, are you sure you want to do the fixit when a custom random function is passed to random_shuffle?

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

30 ↗

(On Diff #89071)

It seems a little weird, but this is the result of clang-format.

70 ↗

(On Diff #89071)

How would you do this? printPretty was the best that I could find fitting my needs. If you have something better fitting, please share :)

81 ↗

(On Diff #89071)

I am not sure what you mean about the original source range. Can I just put that onto the Stream?

Do you have an idea for the comments? Do you mean something like

std::random_shuffle(
   vec.begin(), // Comment
   vec.end() // Comment
);

101 ↗

(On Diff #89071)

Why not? And how would I fix that?

[xazax.hun]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

30 ↗

(On Diff #89071)

I usually just make it one big line and than clang format will do a better reflow. By default it do not remove linebreaks, even if it could improve the layout.

70 ↗

(On Diff #89071)

I was thinking about something like getSourceText of Lexer.

81 ↗

(On Diff #89071)

Or even:

std::random_shuffle(vec.begin(), /*inlinecomment*/ vec.end());

101 ↗

(On Diff #89071)

Because that might cause the code not to compile when the macro is expanded in a different context. It is a conservative approach but other tidy checkers usually do this as well. You can use the isMacroID() method of the source locations.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

81 ↗

(On Diff #89071)

Thanks for you other comments. Can you elaborate on how I might fix this?

[xazax.hun]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

81 ↗

(On Diff #89071)

You might do a different strategy, like not touching the arguments at all, but only inserting a new argument before the closing paren of the function call. This way all the comments should be preserved.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

81 ↗

(On Diff #89071)

I could try that. So just change the name of the function, random_shuffle to shuffle, and then remove the third argument if present and insert third argument. I guess it will work, but it will make the code less elegant.

[madsravn]

Updated the code based on comments received.

[madsravn]

test/clang-tidy/modernize-replace-random-shuffle.cpp

50 ↗

(On Diff #89071)

I re-arranged them. This way the check-fixes does not say the same twice in a row. I am not sure what you mean by 'line ending comments are preserved'. Why shouldn't they be?

The fixit should also be done when a custom random function is passed. random_shuffle will be removed and the signature of the custom random function will be changed. It's hard to do much differently than just issuing a warning.

[malcolm.parsons]

clang-tidy/modernize/ReplaceRandomShuffleCheck.h

21 ↗

(On Diff #89543)

Typo - should be occurrences.
Same in 2 other places.

[madsravn]

Made small changes based on comments.

[madsravn]

Minor update to fix spelling mistake.

[aaron.ballman]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

25 ↗

(On Diff #89919)

Diagnostics are not full sentences. This should probably be: 'std::random_shuffle' has been removed in C++17; use 'std::shuffle' instead.

27 ↗

(On Diff #89919)

I'd feel more comfortable if both of these were const char[] rather than StringRef, because StringRef doesn't typically own the underlying memory and should not be long-lived.

28 ↗

(On Diff #89919)

Instead of adding additional text in this case, would it make sense to use a different diagnostic? e.g., 'std::random_shuffle' has been removed in C++17; use an alternative mechanism instead (or something along those lines). Regardless, it shouldn't be using full sentences.

71 ↗

(On Diff #89919)

No need for this to be a separate variable.

72 ↗

(On Diff #89919)

No need for this to be a separate variable.

77 ↗

(On Diff #89919)

Is there a reason this needs to capture everything by copy? Also, no need for the empty parens. Actually, is the lambda even necessary at all?

105 ↗

(On Diff #89919)

Please don't use auto as the type is not specified in the initialization.

docs/clang-tidy/checks/modernize-replace-random-shuffle.rst

8 ↗

(On Diff #89919)

is -> are

20 ↗

(On Diff #89919)

Both these -> Both of these
with -> with:

[madsravn]

Updated patch according to comments by Ballman.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

Is it OK to capture by reference then? Or how do we want it in llvm?

We need the lambda, because first I need to create the diag with a message based on the count of arguments and then I need to find fixits based on the same count. Example:

string message = "Message for 2 arguments";
if(argumentCount == 3) {
  message = "Message for 3 arguments";
}
auto Diag = diag(startLoc(), message);
if(argumentCount == 3) {
  Diag << FixitHint::FixForThreeArguments();
} else {
  Diag << FixitHint::FixForTwoArguments();
}

So the idea with the lambda is to avoid doing the same if-statement twice.

[aaron.ballman]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

89 ↗

(On Diff #90148)

Should be NewName instead.

77 ↗

(On Diff #89919)

But you call the lambda immediately rather than store it and reuse it? It seems like you should be able to hoist a DiagnosticBuilder variable outside of the if statement and skip the lambda entirely.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

I am not sure what you mean by this. Can you elaborate? Can you give a short example how I would hoist a DiagnosticBuilder out?

I think I tried something like that, but it was not an option.

[aaron.ballman]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

It's entirely possible I'm missing something (I'm distracted with meetings this week), but I was envisioning:

DiagnosticBuilder Diag;
if (MatchedCallExpr->getNumArgs() == 3) {
  Diag =
      diag(MatchedCallExpr->getLocStart(),
           "'std::random_shuffle' has been removed in C++17; use "
           "'std::shuffle' and an alternative random mechanism instead");
  Diag << FixItHint::CreateReplacement(
      MatchedArgumentThree->getSourceRange(),
      "std::mt19937(std::random_device()())");
} else {
  Diag = diag(MatchedCallExpr->getLocStart(),
                    "'std::random_shuffle' has been removed in C++17; use "
                    "'std::shuffle' instead");
  Diag << FixItHint::CreateInsertion(
      MatchedCallExpr->getRParenLoc(),
      ", std::mt19937(std::random_device()())");
}

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

The constructor for DiagnosticBuilder is private. So I cannot do that. The idea had crossed my mind, but I think the lambda expression is nicer to look at.

Should I investigate if there is another way to hoist the DiagnosticBuilder out, like using diag() to make a dummy DiagnosticBuilder outside and then use the copy constructor to assign inside the if-statement? Or can we live with the lambda expression?

[aaron.ballman]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

Ah, okay, that was the bit I was missing. Thank you for being patient. I think the lambda (with the reference capture) is fine as-is.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

Thank you for being patient.

Right back at you. We are working towards the same goal after all :)

For future reference: Should I try to avoid lambda expressions like this?

[aaron.ballman]

Out of curiosity, have you run this over libc++ or libstdc++ test suites involving std::random_shuffle? If so, were the results acceptable?

I think this generally LGTM (aside from the minor nit about naming), but I'd like to hear from @mclow.lists where this meets his needs.

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77 ↗

(On Diff #89919)

No, this sort of expression is fine when it makes the code more simple.

[madsravn]

Last small changes based on comments.

[madsravn]

In D30158#689904, @aaron.ballman wrote:

Out of curiosity, have you run this over libc++ or libstdc++ test suites involving std::random_shuffle? If so, were the results acceptable?

I haven't. Good idea. I will get onto that. I don't have either, so I will just fetch them and set them up.

[madsravn]

Looks good for the two tests the are for random_shuffle in llvm libc++.

[jroelofs]

In D30158#690032, @madsravn wrote:

Looks good for the two tests the are for random_shuffle in llvm libc++.

There were a lot more some time ago, before @mclow.lists performed this transformation on libc++'s testsuite. You might want to try this on the revision before that happened.

[madsravn]

Any updates on this?

[aaron.ballman]

In D30158#696534, @madsravn wrote:

Any updates on this?

Have you run it over the test suite on the revision before random_shuffle was removed from libc++?

[madsravn]

In D30158#698871, @aaron.ballman wrote:

In D30158#696534, @madsravn wrote:

Any updates on this?

Have you run it over the test suite on the revision before random_shuffle was removed from libc++?

I can't find any more tests for random_shuffle. I have looked in the SVN log for from december 2014 until now. It works on the three tests currently in trunk.

[jroelofs]

In D30158#699132, @madsravn wrote:

In D30158#698871, @aaron.ballman wrote:

In D30158#696534, @madsravn wrote:

Any updates on this?

Have you run it over the test suite on the revision before random_shuffle was removed from libc++?

I can't find any more tests for random_shuffle. I have looked in the SVN log for from december 2014 until now. It works on the three tests currently in trunk.

Try just before r294328.

[madsravn]

In D30158#699342, @jroelofs wrote:

In D30158#699132, @madsravn wrote:

In D30158#698871, @aaron.ballman wrote:

In D30158#696534, @madsravn wrote:

Any updates on this?

Have you run it over the test suite on the revision before random_shuffle was removed from libc++?

I can't find any more tests for random_shuffle. I have looked in the SVN log for from december 2014 until now. It works on the three tests currently in trunk.

Try just before r294328.

I can't see any random_shuffle tests in the libc++ repo before r294328 either. I don't know if they aren't there or if I just can't find them. Would you be able to point them out for me with revision and path?

[jroelofs]

In D30158#702760, @madsravn wrote:

In D30158#699342, @jroelofs wrote:

In D30158#699132, @madsravn wrote:

In D30158#698871, @aaron.ballman wrote:

In D30158#696534, @madsravn wrote:

Any updates on this?

Have you run it over the test suite on the revision before random_shuffle was removed from libc++?

I can't find any more tests for random_shuffle. I have looked in the SVN log for from december 2014 until now. It works on the three tests currently in trunk.

Try just before r294328.

I can't see any random_shuffle tests in the libc++ repo before r294328 either. I don't know if they aren't there or if I just can't find them. Would you be able to point them out for me with revision and path?

Did you look at the diff from the commit I mentioned? That's the one that removed them.

[madsravn]

In D30158#702778, @jroelofs wrote:

In D30158#702760, @madsravn wrote:

In D30158#699342, @jroelofs wrote:

In D30158#699132, @madsravn wrote:

In D30158#698871, @aaron.ballman wrote:

In D30158#696534, @madsravn wrote:

Any updates on this?

Have you run it over the test suite on the revision before random_shuffle was removed from libc++?

I can't find any more tests for random_shuffle. I have looked in the SVN log for from december 2014 until now. It works on the three tests currently in trunk.

Try just before r294328.

I can't see any random_shuffle tests in the libc++ repo before r294328 either. I don't know if they aren't there or if I just can't find them. Would you be able to point them out for me with revision and path?

Did you look at the diff from the commit I mentioned? That's the one that removed them.

I found them and I have tested them all. This check works fine on them.

[aaron.ballman]

There are a few small nits I've mentioned, but otherwise LGTM.

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

34–35 ↗

(On Diff #90223)

No need to bind either of these -- the bound name never gets used.

36 ↗

(On Diff #90223)

Can likely pick a better name to bind than "three". ;-) I would recommend "RandomFunc" since that's what the parameter represents.

70 ↗

(On Diff #90223)

Wrap for 80-column (here and elsewhere).

[madsravn]

Small changes to code due to comments.

[aaron.ballman]

This continues to LGTM; do you need someone to land the patch for you?

test/clang-tidy/modernize-replace-random-shuffle.cpp

40 ↗

(On Diff #96303)

Can remove the extra newline.

[madsravn]

In D30158#734810, @aaron.ballman wrote:

This continues to LGTM; do you need someone to land the patch for you?

I will remove the extra newline and land the patch tomorrow. Thanks! :)

clang-tools-extra/trunk/clang-tidy/modernize/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS support)
 
 add_clang_library(clangTidyModernizeModule
   AvoidBindCheck.cpp
   DeprecatedHeadersCheck.cpp
   LoopConvertCheck.cpp
   LoopConvertUtils.cpp
   MakeSmartPtrCheck.cpp
   MakeSharedCheck.cpp
   MakeUniqueCheck.cpp
   ModernizeTidyModule.cpp
   PassByValueCheck.cpp
   RawStringLiteralCheck.cpp
   RedundantVoidArgCheck.cpp
   ReplaceAutoPtrCheck.cpp
+  ReplaceRandomShuffleCheck.cpp
   ReturnBracedInitListCheck.cpp
   ShrinkToFitCheck.cpp
   UseAutoCheck.cpp
   UseBoolLiteralsCheck.cpp
   UseDefaultMemberInitCheck.cpp
   UseEmplaceCheck.cpp
   UseEqualsDefaultCheck.cpp
   UseEqualsDeleteCheck.cpp

clang-tools-extra/trunk/clang-tidy/modernize/ModernizeTidyModule.cpp

 #include "DeprecatedHeadersCheck.h"
 #include "LoopConvertCheck.h"
 #include "MakeSharedCheck.h"
 #include "MakeUniqueCheck.h"
 #include "PassByValueCheck.h"
 #include "RawStringLiteralCheck.h"
 #include "RedundantVoidArgCheck.h"
 #include "ReplaceAutoPtrCheck.h"
+#include "ReplaceRandomShuffleCheck.h"
 #include "ReturnBracedInitListCheck.h"
 #include "ShrinkToFitCheck.h"
 #include "UseAutoCheck.h"
 #include "UseBoolLiteralsCheck.h"
 #include "UseDefaultMemberInitCheck.h"
 #include "UseEmplaceCheck.h"
 #include "UseEqualsDefaultCheck.h"
 #include "UseEqualsDeleteCheck.h"
void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
     CheckFactories.registerCheck<MakeUniqueCheck>("modernize-make-unique");
     CheckFactories.registerCheck<PassByValueCheck>("modernize-pass-by-value");
     CheckFactories.registerCheck<RawStringLiteralCheck>(
         "modernize-raw-string-literal");
     CheckFactories.registerCheck<RedundantVoidArgCheck>(
         "modernize-redundant-void-arg");
     CheckFactories.registerCheck<ReplaceAutoPtrCheck>(
         "modernize-replace-auto-ptr");
+    CheckFactories.registerCheck<ReplaceRandomShuffleCheck>(
+        "modernize-replace-random-shuffle");
     CheckFactories.registerCheck<ReturnBracedInitListCheck>(
         "modernize-return-braced-init-list");
     CheckFactories.registerCheck<ShrinkToFitCheck>("modernize-shrink-to-fit");
     CheckFactories.registerCheck<UseAutoCheck>("modernize-use-auto");
     CheckFactories.registerCheck<UseBoolLiteralsCheck>(
         "modernize-use-bool-literals");
     CheckFactories.registerCheck<UseDefaultMemberInitCheck>(
         "modernize-use-default-member-init");

clang-tools-extra/trunk/clang-tidy/modernize/ReplaceRandomShuffleCheck.h

+//===--- ReplaceRandomShuffleCheck.h - clang-tidy----------------*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_REPLACE_RANDOM_SHUFFLE_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_REPLACE_RANDOM_SHUFFLE_H
+
+#include "../ClangTidy.h"
+#include "../utils/IncludeInserter.h"
+
+namespace clang {
+namespace tidy {
+namespace modernize {
+
+/// std::random_shuffle will be removed as of C++17. This check will find and
+/// replace all occurrences of std::random_shuffle with std::shuffle.
+///
+/// For the user-facing documentation see:
+/// http://clang.llvm.org/extra/clang-tidy/checks/modernize-replace-random-shuffle.html
+class ReplaceRandomShuffleCheck : public ClangTidyCheck {
+public:
+  ReplaceRandomShuffleCheck(StringRef Name, ClangTidyContext *Context);
+  void registerPPCallbacks(CompilerInstance &Compiler) override;
+  void storeOptions(ClangTidyOptions::OptionMap &Opts) override;
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+
+private:
+  std::unique_ptr<utils::IncludeInserter> IncludeInserter;
+  const utils::IncludeSorter::IncludeStyle IncludeStyle;
+};
+
+} // namespace modernize
+} // namespace tidy
+} // namespace clang
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_REPLACE_RANDOM_SHUFFLE_H

clang-tools-extra/trunk/clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

+//===--- ReplaceRandomShuffleCheck.cpp - clang-tidy------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "ReplaceRandomShuffleCheck.h"
+#include "../utils/FixItHintUtils.h"
+#include "clang/AST/ASTContext.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Lex/Preprocessor.h"
+#include "clang/Tooling/FixIt.h"
+
+using namespace clang::ast_matchers;
+
+namespace clang {
+namespace tidy {
+namespace modernize {
+
+ReplaceRandomShuffleCheck::ReplaceRandomShuffleCheck(StringRef Name,
+                                                     ClangTidyContext *Context)
+    : ClangTidyCheck(Name, Context),
+      IncludeStyle(utils::IncludeSorter::parseIncludeStyle(
+          Options.get("IncludeStyle", "llvm"))) {}
+
+void ReplaceRandomShuffleCheck::registerMatchers(MatchFinder *Finder) {
+  if (!getLangOpts().CPlusPlus11)
+    return;
+
+  const auto Begin = hasArgument(0, expr());
+  const auto End = hasArgument(1, expr());
+  const auto RandomFunc = hasArgument(2, expr().bind("randomFunc"));
+  Finder->addMatcher(
+      callExpr(anyOf(allOf(Begin, End, argumentCountIs(2)),
+                     allOf(Begin, End, RandomFunc, argumentCountIs(3))),
+               hasDeclaration(functionDecl(hasName("::std::random_shuffle"))),
+               has(implicitCastExpr(has(declRefExpr().bind("name")))))
+          .bind("match"),
+      this);
+}
+
+void ReplaceRandomShuffleCheck::registerPPCallbacks(
+    CompilerInstance &Compiler) {
+  IncludeInserter = llvm::make_unique<utils::IncludeInserter>(
+      Compiler.getSourceManager(), Compiler.getLangOpts(), IncludeStyle);
+  Compiler.getPreprocessor().addPPCallbacks(
+      IncludeInserter->CreatePPCallbacks());
+}
+
+void ReplaceRandomShuffleCheck::storeOptions(
+    ClangTidyOptions::OptionMap &Opts) {
+  Options.store(Opts, "IncludeStyle",
+                utils::IncludeSorter::toString(IncludeStyle));
+}
+
+void ReplaceRandomShuffleCheck::check(const MatchFinder::MatchResult &Result) {
+  const auto *MatchedDecl = Result.Nodes.getNodeAs<DeclRefExpr>("name");
+  const auto *MatchedArgumentThree = Result.Nodes.getNodeAs<Expr>("randomFunc");
+  const auto *MatchedCallExpr = Result.Nodes.getNodeAs<CallExpr>("match");
+
+  if (MatchedCallExpr->getLocStart().isMacroID())
+    return;
+
+  auto Diag = [&] {
+    if (MatchedCallExpr->getNumArgs() == 3) {
+      auto DiagL =
+          diag(MatchedCallExpr->getLocStart(),
+               "'std::random_shuffle' has been removed in C++17; use "
+               "'std::shuffle' and an alternative random mechanism instead");
+      DiagL << FixItHint::CreateReplacement(
+          MatchedArgumentThree->getSourceRange(),
+          "std::mt19937(std::random_device()())");
+      return DiagL;
+    } else {
+      auto DiagL = diag(MatchedCallExpr->getLocStart(),
+                        "'std::random_shuffle' has been removed in C++17; use "
+                        "'std::shuffle' instead");
+      DiagL << FixItHint::CreateInsertion(
+          MatchedCallExpr->getRParenLoc(),
+          ", std::mt19937(std::random_device()())");
+      return DiagL;
+    }
+  }();
+
+  std::string NewName = "shuffle";
+  StringRef ContainerText = Lexer::getSourceText(
+      CharSourceRange::getTokenRange(MatchedDecl->getSourceRange()),
+      *Result.SourceManager, getLangOpts());
+  if (ContainerText.startswith("std::"))
+    NewName = "std::" + NewName;
+
+  Diag << FixItHint::CreateRemoval(MatchedDecl->getSourceRange());
+  Diag << FixItHint::CreateInsertion(MatchedDecl->getLocStart(), NewName);
+
+  if (Optional<FixItHint> IncludeFixit =
+          IncludeInserter->CreateIncludeInsertion(
+              Result.Context->getSourceManager().getFileID(
+                  MatchedCallExpr->getLocStart()),
+              "random", /*IsAngled=*/true))
+    Diag << IncludeFixit.getValue();
+}
+
+} // namespace modernize
+} // namespace tidy
+} // namespace clang

clang-tools-extra/trunk/docs/ReleaseNotes.rst

- Added `ParameterThreshold` to `readability-function-size`.
 
   Finds functions that have more then `ParameterThreshold` parameters and emits a warning.
 
 - New `hicpp` module
 
   Adds checks that implement the `High Integrity C++ Coding Standard <http://www.codingstandard.com/section/index/>`_ and other safety
   standards. Many checks are aliased to other modules.
 
+- New `modernize-replace-random-shuffle
+  <http://clang.llvm.org/extra/clang-tidy/checks/modernize-replace-random-shuffle.html>`_ check
+
+  Finds and fixes usage of ``std::random_shuffle`` as the function has been removed from C++17.
+
 - New `modernize-return-braced-init-list
   <http://clang.llvm.org/extra/clang-tidy/checks/modernize-return-braced-init-list.html>`_ check
 
   Finds and replaces explicit calls to the constructor in a return statement by
   a braced initializer list so that the return type is not needlessly repeated.
   
 - New `misc-forwarding-reference-overload
   <http://clang.llvm.org/extra/clang-tidy/checks/misc-forwarding-reference-overload.html>`_ check

clang-tools-extra/trunk/docs/clang-tidy/checks/list.rst

.. toctree::
    modernize-deprecated-headers
    modernize-loop-convert
    modernize-make-shared
    modernize-make-unique
    modernize-pass-by-value
    modernize-raw-string-literal
    modernize-redundant-void-arg
    modernize-replace-auto-ptr
+   modernize-replace-random-shuffle
    modernize-return-braced-init-list
    modernize-shrink-to-fit
    modernize-use-auto
    modernize-use-bool-literals
    modernize-use-default-member-init
    modernize-use-emplace
    modernize-use-equals-default
    modernize-use-equals-delete

clang-tools-extra/trunk/docs/clang-tidy/checks/modernize-replace-random-shuffle.rst

+.. title:: clang-tidy - modernize-replace-random-shuffle
+
+modernize-replace-random-shuffle
+================================
+
+This check will find occurrences of ``std::random_shuffle`` and replace it with ``std::shuffle``. In C++17 ``std::random_shuffle`` will no longer be available and thus we need to replace it.
+
+Below are two examples of what kind of occurrences will be found and two examples of what it will be replaced with.
+
+.. code-block:: c++
+
+  std::vector<int> v;
+
+  // First example
+  std::random_shuffle(vec.begin(), vec.end());
+
+  // Second example
+  std::random_shuffle(vec.begin(), vec.end(), randomFun);
+
+Both of these examples will be replaced with:
+
+.. code-block:: c++
+
+  std::shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()()));
+
+The second example will also receive a warning that ``randomFunc`` is no longer supported in the same way as before so if the user wants the same functionality, the user will need to change the implementation of the ``randomFunc``.
+
+One thing to be aware of here is that ``std::random_device`` is quite expensive to initialize. So if you are using the code in a performance critical place, you probably want to initialize it elsewhere. 

clang-tools-extra/trunk/test/clang-tidy/modernize-replace-random-shuffle.cpp

+// RUN: %check_clang_tidy %s modernize-replace-random-shuffle %t -- -- -std=c++11
+
+//CHECK-FIXES: #include <random>
+
+namespace std {
+template <typename T> struct vec_iterator {
+  T *ptr;
+  vec_iterator operator++(int);
+};
+
+template <typename T> struct vector {
+  typedef vec_iterator<T> iterator;
+
+  iterator begin();
+  iterator end();
+};
+
+template <typename FwIt>
+void random_shuffle(FwIt begin, FwIt end);
+
+template <typename FwIt, typename randomFunc>
+void random_shuffle(FwIt begin, FwIt end, randomFunc& randomfunc);
+
+template <typename FwIt>
+void shuffle(FwIt begin, FwIt end);
+} // namespace std
+
+// Random Func
+int myrandom (int i) { return i;}
+
+using namespace std;
+
+int main() {
+  std::vector<int> vec;
+
+  std::random_shuffle(vec.begin(), vec.end());
+  // CHECK-MESSAGE: [[@LINE-1]]:3: warning: 'std::random_shuffle' has been removed in C++17; use 'std::shuffle' instead
+  // CHECK-FIXES: std::shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()()));
+
+  std::shuffle(vec.begin(), vec.end());
+
+  random_shuffle(vec.begin(), vec.end());
+  // CHECK-MESSAGE: [[@LINE-1]]:3: warning: 'std::random_shuffle' has been removed in C++17; use 'std::shuffle' instead
+  // CHECK-FIXES: shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()()));
+  
+  std::random_shuffle(vec.begin(), vec.end(), myrandom);
+  // CHECK-MESSAGE: [[@LINE-1]]:3: warning: 'std::random_shuffle' has been removed in C++17; use 'std::shuffle' and an alternative random mechanism instead
+  // CHECK-FIXES: std::shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()()));
+
+  random_shuffle(vec.begin(), vec.end(), myrandom);
+  // CHECK-MESSAGE: [[@LINE-1]]:3: warning: 'std::random_shuffle' has been removed in C++17; use 'std::shuffle' and an alternative random mechanism instead
+  // CHECK-FIXES: shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()()));
+
+  shuffle(vec.begin(), vec.end());
+
+  return 0;
+}