README.md: Document refute_regex

Add a copy to the implementation, too.

Author: rico-chet

README.md

@@ -728,6 +728,50 @@ Note that the `BASH_REMATCH` array is available immediately after the
 assertion succeeds but is fragile, i.e. prone to being overwritten as a side
 effect of other actions.
 
+### `refute_regex`
+
+This function is similar to `refute_equal` but uses pattern matching instead of
+equality, by wrapping `! [[ value =~ pattern ]]`.
+
+Fail if the value (first parameter) matches the pattern (second parameter).
+
+```bash
+@test 'refute_regex()' {
+  refute_regex 'WhatsApp' 'Threema'
+}
+```
+
+On failure, the value, the pattern and the match are displayed.
+
+```
+@test 'refute_regex()' {
+  refute_regex 'WhatsApp' 'What.'
+}
+
+-- value matches regular expression --
+value    : WhatsApp
+pattern  : What.
+match    : Whats
+case     : sensitive
+--
+```
+
+If the value or pattern is longer than one line then it is displayed in
+*multi-line* format.
+
+An error is displayed if the specified extended regular expression is invalid.
+
+For description of the matching behavior, refer to the documentation of the
+`=~` operator in the
+[Bash manual]: https://www.gnu.org/software/bash/manual/html_node/Conditional-Constructs.html.
+
+Note that the `BASH_REMATCH` array is available immediately after the assertion
+fails but is fragile, i.e. prone to being overwritten as a side effect of other
+actions like calling `run`. Thus, it's good practice to avoid using
+`BASH_REMATCH` in conjunction with `refute_regex()`. The valuable information
+the array contains is the matching part of the value which is printed in the
+failing test log, as mentioned above.
+
 <!-- REFERENCES -->
 
 [bats]: https://github.com/bats-core/bats-core

src/refute_regex.bash

@@ -1,3 +1,46 @@
+# `refute_regex`
+#
+# This function is similar to `refute_equal` but uses pattern matching instead
+# of equality, by wrapping `! [[ value =~ pattern ]]`.
+#
+# Fail if the value (first parameter) matches the pattern (second parameter).
+#
+# ```bash
+# @test 'refute_regex()' {
+#   refute_regex 'WhatsApp' 'Threema'
+# }
+# ```
+#
+# On failure, the value, the pattern and the match are displayed.
+#
+# ```
+# @test 'refute_regex()' {
+#   refute_regex 'WhatsApp' 'What.'
+# }
+#
+# -- value matches regular expression --
+# value    : WhatsApp
+# pattern  : What.
+# match    : Whats
+# case     : sensitive
+# --
+# ```
+#
+# If the value or pattern is longer than one line then it is displayed in
+# *multi-line* format.
+#
+# An error is displayed if the specified extended regular expression is invalid.
+#
+# For description of the matching behavior, refer to the documentation of the
+# `=~` operator in the
+# [Bash manual]: https://www.gnu.org/software/bash/manual/html_node/Conditional-Constructs.html.
+#
+# Note that the `BASH_REMATCH` array is available immediately after the
+# assertion fails but is fragile, i.e. prone to being overwritten as a side
+# effect of other actions like calling `run`. Thus, it's good practice to avoid
+# using `BASH_REMATCH` in conjunction with `refute_regex()`. The valuable
+# information the array contains is the matching part of the value which is
+# printed in the failing test log, as mentioned above.
 refute_regex() {
 	local -r value="${1}"
 	local -r pattern="${2}"