From 08b787796c5f18317feeb4063982a3fd3c650cfd Mon Sep 17 00:00:00 2001 From: ofats Date: Tue, 7 Jul 2020 12:47:27 -0400 Subject: [PATCH] Googletest export Replace ByRef with std::ref everywhere in docs. PiperOrigin-RevId: 320002303 --- googlemock/docs/cheat_sheet.md | 12 ++++++------ googlemock/docs/cook_book.md | 27 ++++++++++++--------------- 2 files changed, 18 insertions(+), 21 deletions(-) diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md index a39c6e9f..85620f71 100644 --- a/googlemock/docs/cheat_sheet.md +++ b/googlemock/docs/cheat_sheet.md @@ -279,9 +279,10 @@ Matcher | Description Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or destructed later. If the compiler complains that `value` doesn't have a public -copy constructor, try wrap it in `ByRef()`, e.g. -`Eq(ByRef(non_copyable_value))`. If you do that, make sure `non_copyable_value` -is not changed afterwards, or the meaning of your matcher will be changed. +copy constructor, try wrap it in `std::ref()`, e.g. +`Eq(std::ref(non_copyable_value))`. If you do that, make sure +`non_copyable_value` is not changed afterwards, or the meaning of your matcher +will be changed. `IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types that can be explicitly converted to Boolean, but are not implicitly converted to @@ -586,13 +587,12 @@ callback type instead of a derived one, e.g. ``` In `InvokeArgument(...)`, if an argument needs to be passed by reference, -wrap it inside `ByRef()`. For example, +wrap it inside `std::ref()`. For example, ```cpp -using ::testing::ByRef; using ::testing::InvokeArgument; ... -InvokeArgument<2>(5, string("Hi"), ByRef(foo)) +InvokeArgument<2>(5, string("Hi"), std::ref(foo)) ``` calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md index 9550d912..3fc1198a 100644 --- a/googlemock/docs/cook_book.md +++ b/googlemock/docs/cook_book.md @@ -1180,15 +1180,14 @@ executed. Just tell gMock that it should save a reference to `bar`, instead of a copy of it. Here's how: ```cpp -using ::testing::ByRef; using ::testing::Eq; using ::testing::Lt; ... // Expects that Foo()'s argument == bar. - EXPECT_CALL(mock_obj, Foo(Eq(ByRef(bar)))); + EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar)))); // Expects that Foo()'s argument < bar. - EXPECT_CALL(mock_obj, Foo(Lt(ByRef(bar)))); + EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar)))); ``` Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the @@ -1851,10 +1850,9 @@ Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function whose return type is not a reference, as doing that usually indicates a user error. So, what shall you do? -Though you may be tempted, DO NOT use `ByRef()`: +Though you may be tempted, DO NOT use `std::ref()`: ```cpp -using testing::ByRef; using testing::Return; class MockFoo : public Foo { @@ -1865,7 +1863,7 @@ class MockFoo : public Foo { int x = 0; MockFoo foo; EXPECT_CALL(foo, GetValue()) - .WillRepeatedly(Return(ByRef(x))); // Wrong! + .WillRepeatedly(Return(std::ref(x))); // Wrong! x = 42; EXPECT_EQ(42, foo.GetValue()); ``` @@ -1881,9 +1879,9 @@ Expected: 42 The reason is that `Return(*value*)` converts `value` to the actual return type of the mock function at the time when the action is *created*, not when it is *executed*. (This behavior was chosen for the action to be safe when `value` is -a proxy object that references some temporary objects.) As a result, `ByRef(x)` -is converted to an `int` value (instead of a `const int&`) when the expectation -is set, and `Return(ByRef(x))` will always return 0. +a proxy object that references some temporary objects.) As a result, +`std::ref(x)` is converted to an `int` value (instead of a `const int&`) when +the expectation is set, and `Return(std::ref(x))` will always return 0. `ReturnPointee(pointer)` was provided to solve this problem specifically. It returns the value pointed to by `pointer` at the time the action is *executed*: @@ -2376,7 +2374,7 @@ using ::testing::InvokeArgument; ``` What if the callable takes an argument by reference? No problem - just wrap it -inside `ByRef()`: +inside `std::ref()`: ```cpp ... @@ -2385,20 +2383,19 @@ inside `ByRef()`: (override)); ... using ::testing::_; - using ::testing::ByRef; using ::testing::InvokeArgument; ... MockFoo foo; Helper helper; ... EXPECT_CALL(foo, Bar(_)) - .WillOnce(InvokeArgument<0>(5, ByRef(helper))); - // ByRef(helper) guarantees that a reference to helper, not a copy of it, - // will be passed to the callback. + .WillOnce(InvokeArgument<0>(5, std::ref(helper))); + // std::ref(helper) guarantees that a reference to helper, not a copy of + // it, will be passed to the callback. ``` What if the callable takes an argument by reference and we do **not** wrap the -argument in `ByRef()`? Then `InvokeArgument()` will *make a copy* of the +argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the argument, and pass a *reference to the copy*, instead of a reference to the original value, to the callable. This is especially handy when the argument is a temporary value: