[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

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

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

7

I think std:: should be added.

[xazax.hun]

Nice check! Thank you for working on this!

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

31

Maybe it would be worth to reflow this literal.

71

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

82

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

102

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

25

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

51

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

31

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

71

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

82

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
);

102

Why not? And how would I fix that?

[xazax.hun]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

31

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.

71

I was thinking about something like getSourceText of Lexer.

82

Or even:

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

102

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

82

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

[xazax.hun]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

82

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

82

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

51

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

22

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

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

27

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

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

No need for this to be a separate variable.

72

No need for this to be a separate variable.

77

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

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

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

8

is -> are

20

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

[madsravn]

Updated patch according to comments by Ballman.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77

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

77

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.

90

Should be NewName instead.

[madsravn]

clang-tidy/modernize/ReplaceRandomShuffleCheck.cpp

77

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

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

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

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

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

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

35–36

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

37

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

71

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

41

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-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-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-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-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 {
+
+static const StringRef ReplaceMessage =
+    "do not use 'random_shuffle'. It is deprecated and replaced by 'shuffle'.";
+
+static const StringRef RandomFunctionMessage =
+    " The old user defined 'RandomFunction' is not usable for 'shuffle'. You "
+    "need to make additional changes if you want a specific random function.";
+
+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 first = hasArgument(0, expr().bind("one"));
+  const auto second = hasArgument(1, expr().bind("two"));
+  const auto third = hasArgument(2, expr().bind("three"));
+  Finder->addMatcher(
+      callExpr(anyOf(allOf(first, second, argumentCountIs(2)),
+                     allOf(first, second, third, 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>("three");
+  const auto *MatchedCallExpr = Result.Nodes.getNodeAs<CallExpr>("match");
+  SourceManager &SM = *Result.SourceManager;
+  LangOptions LangOpts = getLangOpts();
+
+  if (MatchedCallExpr->getLocStart().isMacroID())
+    return;
+
+  auto Diag = [=]() {
+    std::string Message = ReplaceMessage;
+    if (MatchedCallExpr->getNumArgs() == 3) {
+      Message += RandomFunctionMessage;
+      auto DiagL = diag(MatchedCallExpr->getLocStart(), Message);
+      DiagL << FixItHint::CreateReplacement(
+          MatchedArgumentThree->getSourceRange(),
+          "std::mt19937(std::random_device()())");
+      return DiagL;
+    } else {
+      auto DiagL = diag(MatchedCallExpr->getLocStart(), Message);
+      DiagL << FixItHint::CreateInsertion(
+          MatchedCallExpr->getRParenLoc(),
+          ", std::mt19937(std::random_device()())");
+      return DiagL;
+    }
+  }();
+
+  std::string newname = "shuffle";
+  StringRef ContainerText = Lexer::getSourceText(
+      CharSourceRange::getTokenRange(MatchedDecl->getSourceRange()), SM,
+      LangOpts);
+  if (ContainerText.startswith("std::"))
+    newname = "std::" + newname;
+
+  Diag << FixItHint::CreateRemoval(MatchedDecl->getSourceRange());
+  Diag << FixItHint::CreateInsertion(MatchedDecl->getLocStart(), newname);
+
+  if (auto IncludeFixit = IncludeInserter->CreateIncludeInsertion(
+          Result.Context->getSourceManager().getFileID(
+              MatchedCallExpr->getLocStart()),
+          "random", /*IsAngled=*/true))
+    Diag << *IncludeFixit;
+}
+
+} // namespace modernize
+} // namespace tidy
+} // namespace clang

docs/ReleaseNotes.rst

- New `readability-misleading-indentation
 
   Finds misleading indentation where braces should be introduced or the code should be reformatted.
 
 - New `safety-no-assembler
   <http://clang.llvm.org/extra/clang-tidy/checks/safety-no-assembler.html>`_ check
 
   Finds uses of inline assembler.
 
+- 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.
 
 Improvements to include-fixer
 -----------------------------
 
 The improvements are...
 
 Improvements to modularize
 --------------------------
 
 The improvements are...

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

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 is 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 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. 

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: do not use 'random_shuffle'. It is deprecated and replaced by 'shuffle'
+  // 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: do not use 'random_shuffle'. It is deprecated and replaced by 'shuffle'
+  // 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: do not use 'random_shuffle'. It is deprecated and replaced by 'shuffle'. The old user defined 'RandomFunction' is not usable for shuffle. You need to make additional changes if you want a specific random function
+  // 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: do not use 'random_shuffle'. It is deprecated and replaced by 'shuffle'. The old user defined 'RandomFunction' is not usable for shuffle. You need to make additional changes if you want a specific random function
+  // CHECK-FIXES: shuffle(vec.begin(), vec.end(), std::mt19937(std::random_device()()));
+
+  shuffle(vec.begin(), vec.end());
+
+  return 0;
+}