aboutsummaryrefslogtreecommitdiffstats
path: root/googlemock/docs
diff options
context:
space:
mode:
authorAbseil Team <absl-team@google.com>2019-08-02 10:58:20 -0400
committerGennadiy Civil <misterg@google.com>2019-08-02 11:32:23 -0400
commit6a2adc0eedd8ca47f1808dcd315b17666fb2fbe4 (patch)
tree14676d7c55292cbb927e1607390b56075ee945ea /googlemock/docs
parentc8d338c629e598e2afca391602a0ba719541a8dc (diff)
downloadgoogletest-6a2adc0eedd8ca47f1808dcd315b17666fb2fbe4.tar.gz
googletest-6a2adc0eedd8ca47f1808dcd315b17666fb2fbe4.tar.bz2
googletest-6a2adc0eedd8ca47f1808dcd315b17666fb2fbe4.zip
Googletest export
Remove markdown extension which isn't supported on github. PiperOrigin-RevId: 261321329
Diffstat (limited to 'googlemock/docs')
-rw-r--r--googlemock/docs/cheat_sheet.md426
-rw-r--r--googlemock/docs/cook_book.md5
2 files changed, 137 insertions, 294 deletions
diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md
index 3bfc6dde..37c808f5 100644
--- a/googlemock/docs/cheat_sheet.md
+++ b/googlemock/docs/cheat_sheet.md
@@ -223,14 +223,12 @@ and the default action will be taken each time.
A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
`EXPECT_CALL()`, or use it to validate a value directly:
+<!-- mdformat off(github rendering does not support multiline tables) -->
| Matcher | Description |
| :----------------------------------- | :------------------------------------ |
-| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches |
-: : `matcher`. :
-| `ASSERT_THAT(actual_value, matcher)` | The same as |
-: : `EXPECT_THAT(actual_value, matcher)`, :
-: : except that it generates a **fatal** :
-: : failure. :
+| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. |
+| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
+<!-- mdformat on -->
Built-in matchers (where `argument` is the function argument) are divided into
several categories:
@@ -244,6 +242,7 @@ Matcher | Description
#### Generic Comparison
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :--------------------- | :-------------------------------------------------- |
| `Eq(value)` or `value` | `argument == value` |
@@ -254,14 +253,11 @@ Matcher | Description
| `Ne(value)` | `argument != value` |
| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). |
| `NotNull()` | `argument` is a non-null pointer (raw or smart). |
-| `Optional(m)` | `argument` is `optional<>` that contains a value |
-: : matching `m`. :
-| `VariantWith<T>(m)` | `argument` is `variant<>` that holds the |
-: : alternative of type T with a value matching `m`. :
+| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. |
+| `VariantWith<T>(m)` | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. |
| `Ref(variable)` | `argument` is a reference to `variable`. |
-| `TypedEq<type>(value)` | `argument` has type `type` and is equal to `value`. |
-: : You may need to use this instead of `Eq(value)` :
-: : when the mock function is overloaded. :
+| `TypedEq<type>(value)` | `argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded. |
+<!-- mdformat on -->
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
@@ -271,20 +267,14 @@ is not changed afterwards, or the meaning of your matcher will be changed.
#### Floating-Point Matchers {#FpMatchers}
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------------------------- | :--------------------------------- |
-| `DoubleEq(a_double)` | `argument` is a `double` value |
-: : approximately equal to `a_double`, :
-: : treating two NaNs as unequal. :
-| `FloatEq(a_float)` | `argument` is a `float` value |
-: : approximately equal to `a_float`, :
-: : treating two NaNs as unequal. :
-| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value |
-: : approximately equal to `a_double`, :
-: : treating two NaNs as equal. :
-| `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value |
-: : approximately equal to `a_float`, :
-: : treating two NaNs as equal. :
+| `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. |
+| `FloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. |
+| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. |
+| `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. |
+<!-- mdformat on -->
The above matchers use ULP-based comparison (the same as used in googletest).
They automatically pick a reasonable error bound based on the absolute value of
@@ -293,43 +283,32 @@ which requires comparing two NaNs for equality to return false. The
`NanSensitive*` version instead treats two NaNs as equal, which is often what a
user wants.
-| Matcher | Description |
-| :---------------------------------- | :------------------------------------- |
-| `DoubleNear(a_double, | `argument` is a `double` value close |
-: max_abs_error)` : to `a_double` (absolute error <= :
-: : `max_abs_error`), treating two NaNs as :
-: : unequal. :
-| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to |
-: : `a_float` (absolute error <= :
-: : `max_abs_error`), treating two NaNs as :
-: : unequal. :
-| `NanSensitiveDoubleNear(a_double, | `argument` is a `double` value close |
-: max_abs_error)` : to `a_double` (absolute error <= :
-: : `max_abs_error`), treating two NaNs as :
-: : equal. :
-| `NanSensitiveFloatNear(a_float, | `argument` is a `float` value close to |
-: max_abs_error)` : `a_float` (absolute error <= :
-: : `max_abs_error`), treating two NaNs as :
-: : equal. :
+<!-- mdformat off(no multiline tables) -->
+| Matcher | Description |
+| :------------------------------------------------ | :----------------------- |
+| `DoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal. |
+| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. |
+| `NanSensitiveDoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. |
+| `NanSensitiveFloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. |
+<!-- mdformat on -->
#### String Matchers
The `argument` can be either a C string or a C++ string object:
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :---------------------- | :------------------------------------------------- |
| `ContainsRegex(string)` | `argument` matches the given regular expression. |
| `EndsWith(suffix)` | `argument` ends with string `suffix`. |
| `HasSubstr(string)` | `argument` contains `string` as a sub-string. |
-| `MatchesRegex(string)` | `argument` matches the given regular expression |
-: : with the match starting at the first character and :
-: : ending at the last character. :
+| `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. |
| `StartsWith(prefix)` | `argument` starts with string `prefix`. |
| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. |
-| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring |
-: : case. :
+| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. |
| `StrEq(string)` | `argument` is equal to `string`. |
| `StrNe(string)` | `argument` is not equal to `string`. |
+<!-- mdformat on -->
`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They
use the regular expression syntax defined
@@ -343,99 +322,28 @@ or simply `expected_container` to match a container exactly. If you want to
write the elements in-line, match them more flexibly, or get more informative
messages, you can use:
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :---------------------------------------- | :------------------------------- |
-| `BeginEndDistanceIs(m)` | `argument` is a container whose |
-: : `begin()` and `end()` iterators :
-: : are separated by a number of :
-: : increments matching `m`. E.g. :
-: : `BeginEndDistanceIs(2)` or :
-: : `BeginEndDistanceIs(Lt(2))`. For :
-: : containers that define a :
-: : `size()` method, `SizeIs(m)` may :
-: : be more efficient. :
-| `ContainerEq(container)` | The same as `Eq(container)` |
-: : except that the failure message :
-: : also includes which elements are :
-: : in one container but not the :
-: : other. :
-| `Contains(e)` | `argument` contains an element |
-: : that matches `e`, which can be :
-: : either a value or a matcher. :
-| `Each(e)` | `argument` is a container where |
-: : *every* element matches `e`, :
-: : which can be either a value or a :
-: : matcher. :
-| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, |
-: : where the *i*-th element matches :
-: : `ei`, which can be a value or a :
-: : matcher. :
-| `ElementsAreArray({e0, e1, ..., en})`, | The same as `ElementsAre()` |
-: `ElementsAreArray(a_container)`, : except that the expected element :
-: `ElementsAreArray(begin, end)`, : values/matchers come from an :
-: `ElementsAreArray(array)`, or : initializer list, STL-style :
-: `ElementsAreArray(array, count)` : container, iterator range, or :
-: : C-style array. :
-| `IsEmpty()` | `argument` is an empty container |
-: : (`container.empty()`). :
-| `IsFalse()` | `argument` evaluates to `false` |
-: : in a Boolean context. :
-| `IsSubsetOf({e0, e1, ..., en})`, | `argument` matches |
-: `IsSubsetOf(a_container)`, : `UnorderedElementsAre(x0, x1, :
-: `IsSubsetOf(begin, end)`, : ..., xk)` for some subset `{x0, :
-: `IsSubsetOf(array)`, or : x1, ..., xk}` of the expected :
-: `IsSubsetOf(array, count)` : matchers. :
-| `IsSupersetOf({e0, e1, ..., en})`, | Some subset of `argument` |
-: `IsSupersetOf(a_container)`, : matches :
-: `IsSupersetOf(begin, end)`, : `UnorderedElementsAre(`expected :
-: `IsSupersetOf(array)`, or : matchers`)`. :
-: `IsSupersetOf(array, count)` : :
-| `IsTrue()` | `argument` evaluates to `true` |
-: : in a Boolean context. :
-| `Pointwise(m, container)`, `Pointwise(m, | `argument` contains the same |
-: {e0, e1, ..., en})` : number of elements as in :
-: : `container`, and for all i, (the :
-: : i-th element in `argument`, the :
-: : i-th element in `container`) :
-: : match `m`, which is a matcher on :
-: : 2-tuples. E.g. `Pointwise(Le(), :
-: : upper_bounds)` verifies that :
-: : each element in `argument` :
-: : doesn't exceed the corresponding :
-: : element in `upper_bounds`. See :
-: : more detail below. :
-| `SizeIs(m)` | `argument` is a container whose |
-: : size matches `m`. E.g. :
-: : `SizeIs(2)` or `SizeIs(Lt(2))`. :
-| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, |
-: : and under *some* permutation of :
-: : the elements, each element :
-: : matches an `ei` (for a different :
-: : `i`), which can be a value or a :
-: : matcher. :
-| `UnorderedElementsAreArray({e0, e1, ..., | The same as |
-: en})`, : `UnorderedElementsAre()` except :
-: `UnorderedElementsAreArray(a_container)`, : that the expected element :
-: `UnorderedElementsAreArray(begin, end)`, : values/matchers come from an :
-: `UnorderedElementsAreArray(array)`, or : initializer list, STL-style :
-: `UnorderedElementsAreArray(array, count)` : container, iterator range, or :
-: : C-style array. :
-| `UnorderedPointwise(m, container)`, | Like `Pointwise(m, container)`, |
-: `UnorderedPointwise(m, {e0, e1, ..., : but ignores the order of :
-: en})` : elements. :
-| `WhenSorted(m)` | When `argument` is sorted using |
-: : the `<` operator, it matches :
-: : container matcher `m`. E.g. :
-: : `WhenSorted(ElementsAre(1, 2, :
-: : 3))` verifies that `argument` :
-: : contains elements 1, 2, and 3, :
-: : ignoring order. :
-| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, |
-: : except that the given comparator :
-: : instead of `<` is used to sort :
-: : `argument`. E.g. :
-: : `WhenSortedBy(std\:\:greater(), :
-: : ElementsAre(3, 2, 1))`. :
+| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. |
+| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. |
+| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. |
+| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. |
+| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. |
+| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
+| `IsEmpty()` | `argument` is an empty container (`container.empty()`). |
+| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. |
+| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. |
+| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. |
+| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. |
+| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. |
+| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. |
+| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. |
+| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
+| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. |
+| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements 1, 2, and 3, ignoring order. |
+| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))`. |
+<!-- mdformat on -->
**Notes:**
@@ -462,41 +370,31 @@ messages, you can use:
#### Member Matchers
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------------------------ | :----------------------------------------- |
-| `Field(&class::field, m)` | `argument.field` (or `argument->field` |
-: : when `argument` is a plain pointer) :
-: : matches matcher `m`, where `argument` is :
-: : an object of type _class_. :
-| `Key(e)` | `argument.first` matches `e`, which can be |
-: : either a value or a matcher. E.g. :
-: : `Contains(Key(Le(5)))` can verify that a :
-: : `map` contains a key `<= 5`. :
-| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` |
-: : field matches `m1` and `second` field :
-: : matches `m2`. :
-| `Property(&class::property, m)` | `argument.property()` (or |
-: : `argument->property()` when `argument` is :
-: : a plain pointer) matches matcher `m`, :
-: : where `argument` is an object of type :
-: : _class_. :
+| `Field(&class::field, m)` | `argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. |
+| `Key(e)` | `argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`. |
+| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. |
+| `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. |
+<!-- mdformat on -->
#### Matching the Result of a Function, Functor, or Callback
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :--------------- | :------------------------------------------------ |
-| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a |
-: : function or functor. :
+| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |
+<!-- mdformat on -->
#### Pointer Matchers
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------------------ | :---------------------------------------------- |
-| `Pointee(m)` | `argument` (either a smart pointer or a raw |
-: : pointer) points to a value that matches matcher :
-: : `m`. :
-| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through |
-: : `dynamic_cast<T>()`, it matches matcher `m`. :
+| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. |
+| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. |
+<!-- mdformat on -->
<!-- GOOGLETEST_CM0026 DO NOT DELETE -->
@@ -520,82 +418,61 @@ Matcher | Description
You can use the following selectors to pick a subset of the arguments (or
reorder them) to participate in the matching:
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------------------- | :---------------------------------------------- |
-| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in |
-: : `.With(AllArgs(m))`. :
-| `Args<N1, N2, ..., Nk>(m)` | The tuple of the `k` selected (using 0-based |
-: : indices) arguments matches `m`, e.g. `Args<1, :
-: : 2>(Eq())`. :
+| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. |
+| `Args<N1, N2, ..., Nk>(m)` | The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`. |
+<!-- mdformat on -->
#### Composite Matchers
You can make a matcher from one or more other matchers:
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------------------------- | :-------------------------------------- |
-| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers |
-: : `m1` to `mn`. :
-| `AllOfArray({m0, m1, ..., mn})`, | The same as `AllOf()` except that the |
-: `AllOfArray(a_container)`, : matchers come from an initializer list, :
-: `AllOfArray(begin, end)`, : STL-style container, iterator range, or :
-: `AllOfArray(array)`, or : C-style array. :
-: `AllOfArray(array, count)` : :
-| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the |
-: : matchers `m1` to `mn`. :
-| `AnyOfArray({m0, m1, ..., mn})`, | The same as `AnyOf()` except that the |
-: `AnyOfArray(a_container)`, : matchers come from an initializer list, :
-: `AnyOfArray(begin, end)`, : STL-style container, iterator range, or :
-: `AnyOfArray(array)`, or : C-style array. :
-: `AnyOfArray(array, count)` : :
-| `Not(m)` | `argument` doesn't match matcher `m`. |
+| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
+| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
+| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. |
+| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
+| `Not(m)` | `argument` doesn't match matcher `m`. |
+<!-- mdformat on -->
<!-- GOOGLETEST_CM0028 DO NOT DELETE -->
#### Adapters for Matchers
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :---------------------- | :------------------------------------ |
-| `MatcherCast<T>(m)` | casts matcher `m` to type |
-: : `Matcher<T>`. :
-| `SafeMatcherCast<T>(m)` | [safely |
-: : casts](cook_book.md#casting-matchers) :
-: : matcher `m` to type `Matcher<T>`. :
-| `Truly(predicate)` | `predicate(argument)` returns |
-: : something considered by C++ to be :
-: : true, where `predicate` is a function :
-: : or functor. :
+| `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. |
+| `SafeMatcherCast<T>(m)` | [safely casts](cook_book.md#casting-matchers) matcher `m` to type `Matcher<T>`. |
+| `Truly(predicate)` | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. |
+<!-- mdformat on -->
`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
which must be a permanent callback.
#### Using Matchers as Predicates {#MatchersAsPredicatesCheat}
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :---------------------------- | :------------------------------------------ |
-| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. |
-: : You can use `Matches(m)` alone as a unary :
-: : functor. :
-| `ExplainMatchResult(m, value, | evaluates to `true` if `value` matches `m`, |
-: result_listener)` : explaining the result to `result_listener`. :
-| `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
+| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. |
+| `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. |
+| `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
+<!-- mdformat on -->
#### Defining Matchers
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :----------------------------------- | :------------------------------------ |
-| `MATCHER(IsEven, "") { return (arg % | Defines a matcher `IsEven()` to match |
-: 2) == 0; }` : an even number. :
-| `MATCHER_P(IsDivisibleBy, n, "") { | Defines a macher `IsDivisibleBy(n)` |
-: *result_listener << "where the : to match a number divisible by `n`. :
-: remainder is " << (arg % n); return : :
-: (arg % n) == 0; }` : :
-| `MATCHER_P2(IsBetween, a, b, | Defines a matcher `IsBetween(a, b)` |
-: std\:\:string(negation ? "isn't" \: : to match a value in the range [`a`, :
-: "is") + " between " + : `b`]. :
-: PrintToString(a) + " and " + : :
-: PrintToString(b)) { return a <= arg : :
-: && arg <= b; }` : :
+| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |
+| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a macher `IsDivisibleBy(n)` to match a number divisible by `n`. |
+| `MATCHER_P2(IsBetween, a, b, std::string(negation ? "isn't" : "is") + " between " + PrintToString(a) + " and " + PrintToString(b)) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. |
+<!-- mdformat on -->
**Notes:**
@@ -612,78 +489,51 @@ which must be a permanent callback.
#### Returning a Value
+<!-- mdformat off(no multiline tables) -->
| | |
| :-------------------------- | :-------------------------------------------- |
| `Return()` | Return from a `void` mock function. |
-| `Return(value)` | Return `value`. If the type of `value` is |
-: : different to the mock function's return type, :
-: : `value` is converted to the latter type <i>at :
-: : the time the expectation is set</i>, not when :
-: : the action is executed. :
+| `Return(value)` | Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type <i>at the time the expectation is set</i>, not when the action is executed. |
| `ReturnArg<N>()` | Return the `N`-th (0-based) argument. |
-| `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different |
-: : object is created each time. :
+| `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. |
| `ReturnNull()` | Return a null pointer. |
| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. |
| `ReturnRef(variable)` | Return a reference to `variable`. |
-| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the |
-: : copy lives as long as the action. :
+| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. |
+<!-- mdformat on -->
#### Side Effects
+<!-- mdformat off(no multiline tables) -->
| | |
| :--------------------------------- | :-------------------------------------- |
-| `Assign(&variable, value)` | Assign `value` to variable. |
-| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, |
-: : which must be a pointer. :
-| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to |
-: : `*pointer`. :
-| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th |
-: : (0-based) argument to `*pointer`. :
-| `SetArgReferee<N>(value)` | Assign value to the variable referenced |
-: : by the `N`-th (0-based) argument. :
-| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed |
-: : by the `N`-th (0-based) argument. :
-| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. |
-: : Deprecated. Will be removed in v1.7.0. :
-| `SetArrayArgument<N>(first, last)` | Copies the elements in source range |
-: : [`first`, `last`) to the array pointed :
-: : to by the `N`-th (0-based) argument, :
-: : which can be either a pointer or an :
-: : iterator. The action does not take :
-: : ownership of the elements in the source :
-: : range. :
-| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return |
-: : `value`. :
-| `Throw(exception)` | Throws the given exception, which can |
-: : be any copyable value. Available since :
-: : v1.1.0. :
+| `Assign(&variable, value)` | Assign `value` to variable. |
+| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |
+| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |
+| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. |
+| `SetArgReferee<N>(value)` | Assign value to the variable referenced by the `N`-th (0-based) argument. |
+| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. |
+| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. |
+| `SetArrayArgument<N>(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. |
+| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. |
+| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
+<!-- mdformat on -->
#### Using a Function, Functor, or Lambda as an Action
In the following, by "callable" we mean a free function, `std::function`,
functor, or lambda.
+<!-- mdformat off(no multiline tables) -->
| | |
| :---------------------------------- | :------------------------------------- |
-| `f` | Invoke f with the arguments passed to |
-: : the mock function, where f is a :
-: : callable. :
-| `Invoke(f)` | Invoke `f` with the arguments passed |
-: : to the mock function, where `f` can be :
-: : a global/static function or a functor. :
-| `Invoke(object_pointer, | Invoke the method on the object with |
-: &class\:\:method)` : the arguments passed to the mock :
-: : function. :
-| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a |
-: : global/static function or a functor. :
-: : `f` must take no arguments. :
-| `InvokeWithoutArgs(object_pointer, | Invoke the method on the object, which |
-: &class\:\:method)` : takes no arguments. :
-| `InvokeArgument<N>(arg1, arg2, ..., | Invoke the mock function's `N`-th |
-: argk)` : (0-based) argument, which must be a :
-: : function or a functor, with the `k` :
-: : arguments. :
+| `f` | Invoke f with the arguments passed to the mock function, where f is a callable. |
+| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. |
+| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. |
+| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. |
+| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. |
+| `InvokeArgument<N>(arg1, arg2, ..., argk)` | Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments. |
+<!-- mdformat on -->
The return value of the invoked function is used as the return value of the
action.
@@ -725,10 +575,11 @@ value, and `foo` by reference.
#### Default Action
+<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------ | :----------------------------------------------------- |
-| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the |
-: : built-in one). :
+| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
+<!-- mdformat on -->
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a
composite action - trying to do so will result in a run-time error.
@@ -737,19 +588,15 @@ composite action - trying to do so will result in a run-time error.
#### Composite Actions
+<!-- mdformat off(no multiline tables) -->
| | |
| :----------------------------- | :------------------------------------------ |
-| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the |
-: : result of `an` in each invocation. The :
-: : first `n - 1` sub-actions must return void. :
-| `IgnoreResult(a)` | Perform action `a` and ignore its result. |
-: : `a` must not return void. :
-| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the |
-: : mock function to action `a` and perform it. :
-| `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of |
-: : the mock function to action `a` and perform :
-: : it. :
-| `WithoutArgs(a)` | Perform action `a` without any arguments. |
+| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void. |
+| `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. |
+| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. |
+| `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. |
+| `WithoutArgs(a)` | Perform action `a` without any arguments. |
+<!-- mdformat on -->
#### Defining Actions
@@ -766,17 +613,13 @@ composite action - trying to do so will result in a run-time error.
</tr>
</table>
+<!-- mdformat off(no multiline tables) -->
| | |
| :--------------------------------- | :-------------------------------------- |
-| `ACTION(Sum) { return arg0 + arg1; | Defines an action `Sum()` to return the |
-: }` : sum of the mock function's argument #0 :
-: : and #1. :
-| `ACTION_P(Plus, n) { return arg0 + | Defines an action `Plus(n)` to return |
-: n; }` : the sum of the mock function's :
-: : argument #0 and `n`. :
-| `ACTION_Pk(Foo, p1, ..., pk) { | Defines a parameterized action `Foo(p1, |
-: statements; }` : ..., pk)` to execute the given :
-: : `statements`. :
+| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. |
+| `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. |
+| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. |
+<!-- mdformat on -->
The `ACTION*` macros cannot be used inside a function or class.
@@ -785,15 +628,15 @@ The `ACTION*` macros cannot be used inside a function or class.
These are used in `Times()` to specify how many times a mock function will be
called:
+<!-- mdformat off(no multiline tables) -->
| | |
| :---------------- | :----------------------------------------------------- |
| `AnyNumber()` | The function can be called any number of times. |
| `AtLeast(n)` | The call is expected at least `n` times. |
| `AtMost(n)` | The call is expected at most `n` times. |
-| `Between(m, n)` | The call is expected between `m` and `n` (inclusive) |
-: : times. :
-| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, |
-: : the call should never happen when `n` is 0. :
+| `Between(m, n)` | The call is expected between `m` and `n` (inclusive) times. |
+| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0. |
+<!-- mdformat on -->
### Expectation Order
@@ -918,10 +761,9 @@ See this [recipe](cook_book.md#using-check-points) for one application of it.
### Flags
+<!-- mdformat off(no multiline tables) -->
| Flag | Description |
| :----------------------------- | :---------------------------------------- |
-| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as |
-: : failures. :
-| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, |
-: : `warning`, or `error`) of Google Mock :
-: : messages. :
+| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. |
+| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. |
+<!-- mdformat on -->
diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md
index 676560bf..0352ef65 100644
--- a/googlemock/docs/cook_book.md
+++ b/googlemock/docs/cook_book.md
@@ -1195,11 +1195,12 @@ that satisfies matcher `m`.
For example:
+<!-- mdformat off(github rendering does not support multiline tables) -->
| Expression | Description |
| :--------------------------- | :--------------------------------------- |
| `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
-| `Property(&Foo::name, | Matches `x` where `x.name()` starts with |
-: StartsWith("John "))` : `"John "`. :
+| `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
+<!-- mdformat on -->
Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument
and be declared as `const`.