Add tests & docs for match operator

docs/api-reference.md

@@ -16,6 +16,9 @@
 
 ## Operators
 
+### `==`, `!=`, `>`, `<`, `>=`, `<=`
+
+The same as the standrd C operators:
 - `==`
   - Requires actual to be equal to expected.
 - `!=`
@@ -28,14 +31,46 @@
   - Requires actual to be greater than or equal to expected.
 - `<=`
   - Requires actual to be less than or equal to expected.
+
+### `in` and `not in`
+
+Only defined for strings and array elements.
+
 - `in`
   - Requires actual to be in expected.
-  - Only defined for strings and array elements
-    - `EXPECT_STR("abc", in, "abcdef")`
-    - `EXPECT_INT_ARRAY_ELEMENT(1, in, {1, 2, 3})`
 - `not in`
   - **Inverse of above**: requires actual to **not** be in expected.
-  - Only defined for strings and array elements
+
+Examples:
+- `EXPECT_STR("abc", in, "abcdef")`
+- `EXPECT_INT_ARRAY_ELEMENT(1, in, {1, 2, 3})`
+
+### `match` and `not match`
+
+Only defined for strings.
+
+- `match`
+  - Requires actual to match expected.
+- `not match`
+  - **Inverse of above**: requires actual to **not** match expected.
+
+Examples:
+- `EXPECT_STR("abc", match, "abc")`
+- `EXPECT_STR("a a char", match, "a $c char")`
+- `EXPECT_STR("a 123 number", match, "a $i number")`
+- `EXPECT_STR("abc", not match, "def")`
+- See [sample tests](../tests/str.c) for more
+
+Match specifiers are specified with `$`:
+- `$i`, `$d` = match a integer (0-9)
+- `$c` = match a single character
+- `$f` = match a float (0-9, a single . allowed)
+- `$a` = match alpha-chars (a-z and A-Z)
+- `$w` = match a word (matches anything non-whitespace)
+- `$s` = match a string (at least 1 character)
+- `$$` = a literal $
+- Anything else = literal match
+- **Note:** Having two greedy operators like $s without a literal match between them (`$s$s`) will fail
 
 ## Expect Assertions
 

docs/getting-started.md

@@ -132,7 +132,7 @@ TEST("arrays")
 
 ## In Operator
 
-Caught also provides a convience `in` and `not in` operator you can use with strings and arrays:
+Caught also provides a convenience `in` and `not in` operator you can use with strings and arrays:
 
 ```c
 TEST("str - in")
@@ -145,6 +145,37 @@ TEST("str - in")
 }
 ```
 
+## Match Operator
+
+Caught also provides a convenience `match` and `not match` operator you can use with strings, where `$specifier` is used to match things.
+
+See the [match operator](./api-reference.md#match-and-not-match) in the API reference for more details.
+
+```c
+TEST("str - match")
+{
+    EXPECT_STR("abc", match, "abc");
+    EXPECT_STR("a a char", match, "a $c char");
+    EXPECT_STR("a 123 number", match, "a $i number");
+    EXPECT_STR("a 123.456 float", match, "a $f float");
+    EXPECT_STR("the alphabet match", match, "the $a match");
+    EXPECT_STR("the word123 match", match, "the $w match");
+    EXPECT_STR("a very long string", match, "a $s string");
+    EXPECT_STR("a literal $ can work", match, "a literal $$ can work");
+
+    EXPECT_STR("a 123c number char", match, "a $i$c number char");
+    EXPECT_STR("two nice looking - awesome beings strings", match, "two $s - $s strings");
+
+    EXPECT_STR("abc", not match, "def");
+    EXPECT_STR("the char is missing: ", not match, "the char is missing: $c");
+    EXPECT_STR("the no alpha 123 match", not match, "the no alpha $a match");
+    EXPECT_STR("the no whitespace \t match", not match, "the no whitespace $w match");
+    EXPECT_STR("the string is missing: ", not match, "the string is missing: $s");
+    EXPECT_STR("not a match", not match, "not a $s match");
+    EXPECT_STR("too greedy", not match, "$s$s");
+}
+```
+
 ## Exit & Signal Assertions
 
 If your code exits with a exit or signal, you can test it like this:

tests/str.c

@@ -26,6 +26,29 @@ TEST("str - in")
     EXPECT_STR("123", not in, "12121223141246");
 }
 
+TEST("str - match")
+{
+    EXPECT_STR("abc", match, "abc");
+    EXPECT_STR("a a char", match, "a $c char");
+    EXPECT_STR("a 123 number", match, "a $i number");
+    EXPECT_STR("a 123.456 float", match, "a $f float");
+    EXPECT_STR("the alphabet match", match, "the $a match");
+    EXPECT_STR("the word123 match", match, "the $w match");
+    EXPECT_STR("a very long string", match, "a $s string");
+    EXPECT_STR("a literal $ can work", match, "a literal $$ can work");
+
+    EXPECT_STR("a 123c number char", match, "a $i$c number char");
+    EXPECT_STR("two nice looking - awesome beings strings", match, "two $s - $s strings");
+
+    EXPECT_STR("abc", not match, "def");
+    EXPECT_STR("the char is missing: ", not match, "the char is missing: $c");
+    EXPECT_STR("the no alpha 123 match", not match, "the no alpha $a match");
+    EXPECT_STR("the no whitespace \t match", not match, "the no whitespace $w match");
+    EXPECT_STR("the string is missing: ", not match, "the string is missing: $s");
+    EXPECT_STR("not a match", not match, "not a $s match");
+    EXPECT_STR("too greedy", not match, "$s$s");
+}
+
 TEST("str - ptrs")
 {
     char *array[] = {"abc", "def", NULL};